# Observability Setup

> Add or improve service metrics, structured logs, traces, health signals, dashboards and alerts. Use when instrumentation or operational visibility is missing or misleading; use `nav-troubleshoot` to investigate an active incident with existing telemetry.

- Skill: `navikt/observability-setup-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add navikt/observability-setup-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/navikt/observability-setup-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: navikt (https://skillmd.com/u/navikt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/navikt/observability-setup-2

---

# Observability setup

> **OpenCode v1:** Skill names below are exact IDs from the active catalog, not slash commands. Load them with the native `skill` tool. Slash commands are direct user entry points only.

Build from actual runtime: metrics show change, logs give event context, and
traces show where time and failures occur.

## Discover current state

Do not assume framework, package, paths, endpoints, metric names, labels,
service names, environments, backends, dashboard location or alert routing.

Inspect consumer evidence for:

- runtime, instrumentation, registry/exporter and scrape configuration
- logger format, approved fields, language and correlation
- trace instrumentation, service identity and propagation
- probe contracts, metrics, dashboards, alerts, runbooks and SLOs
- deployment labels, owners, routing and prohibited data

If a required name or policy is not discoverable, ask. Verify time-sensitive
Nais and library guidance against current authoritative documentation.

## Design workflow

1. Name the user-visible or operational question.
2. Inventory existing signals and their exact names/labels.
3. Reuse an established pattern before adding a parallel registry or field.
4. Add the smallest signal that changes diagnosis or response.
5. Define how it will be queried, visualized or alerted on.
6. Validate output, ownership, runbook and removal criteria.

### Metrics

- Use names and units consistent with the consumer's registry and conventions.
- Keep labels low-cardinality and bounded.
- Never use personal identifiers, tokens, raw URLs, correlation IDs or payload
  values as metric labels.
- Confirm histogram buckets exist before relying on percentile queries.
- Prefer outcome and saturation signals over implementation counters with no
  operational use.

### Logs

- Follow the consumer's format, language and approved field set.
- Log event and outcome, not full request, token, payload or personal data.
- Reuse existing correlation fields and propagation.
- Temporary debug logging requires approval and an explicit removal plan.

### Traces

- Confirm instrumentation and service identity before adding manual spans.
- Propagate the consumer's verified context standard across supported
  boundaries.
- Do not duplicate personal or secret data in span names or attributes.

### Health

- Liveness answers whether restarting this process can help.
- Readiness answers whether this instance should receive its intended work.
- Discover actual workload and dependency semantics; a queue consumer, job and
  HTTP service may need different contracts.
- Keep probes fast and free of sensitive detail.

## Progressive references

- [Micrometer and Ktor](./references/micrometer.md)
- [PromQL, LogQL and dashboards](./references/promql-logql.md)
- [Alert design](./references/alerting.md)

## Approval boundary

Drafts and read-only inspection come first. Before editing code/config,
dashboards, alerts, thresholds or routing, publishing, deploying, or running
sensitive live queries, show the target and plan and get explicit approval.

## Grenser

### Alltid

- Derive names and labels from consumer evidence.
- Tie every new signal to an operational question.
- Protect personal data, credentials and payloads.
- Validate that the signal is actually emitted and queryable.

### Spør først

- New high-cardinality dimensions or retained data.
- Dashboard, alert, routing or production-threshold changes.
- Every external write or sensitive runtime inspection.

### Aldri

- Invent service, metric, label, environment or routing names.
- Add instrumentation with no intended consumer.
- Use observability as a reason to expose secrets or personal data.