agentsclimarketplace

Observability checklist

Skill atuljha23/holocron/skills/observability-checklist

Role-aware Claude Code plugin: 10 specialist agents (frontend, backend, QA, a11y, perf, security, architect, debugger, code-reviewer, docs), 15 domain commands, 8 skills, and a SQLite-backed learning crystal that compounds your corrections across sessions.

Install
npx -y skills add atuljha23/holocron --skill observability-checklist

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

What good observability looks like — structured logs, trace spans, metrics, correlation ids, and the instrumentation rules that turn logs into answers. Use when adding a feature, reviewing a service, or debugging a prod issue.

SKILL.md

4.2 KB, as published. Nobody here has run it

Observability checklist

The goal isn't logs — it's answering "what happened" in under five minutes at 2am. Design backward from the question.

Logs

Structured or nothing

  • JSON (or logfmt), not free text.
  • Every log has: ts, level, service, request_id, msg, and relevant fields.
  • Fields are snake_case or camelCase — pick one per service. No mixing.
  • Durations in milliseconds as numbers, not "took 2s" strings.

Levels are a contract

  • error: something failed the user can't recover from. Alert-worthy.
  • warn: something unexpected but handled. Review-worthy.
  • info: the shape of normal traffic. Sampling OK.
  • debug: developer-only. Off in prod.
  • Don't invent new levels.

What to log

  • Request entry (method, path, user, request_id).
  • Outcome (status, duration).
  • Branch decisions that matter (authz check, cache hit/miss, retry).
  • Errors with the full context you need to reproduce.

What NOT to log

  • Secrets, tokens, passwords, PII — scrub before logging.
  • The full request body by default. Specific fields, yes. Everything, no.
  • Stack traces as separate lines — include as a stack field so they stay with the event.

Traces

Span per unit of work

  • HTTP request handler = 1 span.
  • Outbound call = child span.
  • DB query = child span (with db.statement truncated / hashed, not raw if PII risk).
  • Background job step = 1 span.

Mandatory attributes

  • service.name, service.version.
  • For HTTP: http.method, http.route, http.status_code.
  • For DB: db.system, db.operation.
  • For errors: exception.type, exception.message.

Propagation

  • Every outbound request carries trace context headers.
  • Every background job enqueues with trace context.
  • A trace that ends at the HTTP edge and restarts at the worker is useless.

Metrics

RED for services

  • Rate — requests per second, per endpoint.
  • Errors — error rate, per endpoint.
  • Duration — p50/p95/p99, per endpoint.

USE for resources

  • Utilization — % of capacity in use.
  • Saturation — queue depth / wait time.
  • Errors — failed operations.

Cardinality discipline

  • No unbounded tags (user_id, tenant_id, url with params). They explode your TSDB bill.
  • Pre-aggregate cardinal dimensions; keep labels coarse.
  • http.route (the template), not http.url (the instance).

Correlation

  • request_id in: logs, traces (as request.id attr), response headers, error payloads.
  • trace_id in: logs (auto-injected by SDK), response headers for user bug reports.
  • A user reporting "I got a 500" should give you enough to find the request — the request_id is visible and searchable.

Per-language

Node

  • Pino or Winston with JSON transport.
  • OpenTelemetry SDK (@opentelemetry/sdk-node).
  • Prom-client for metrics.

Python

  • structlog with ProcessorFormatter.
  • opentelemetry-sdk + opentelemetry-instrumentation-*.
  • prometheus_client.

Go

  • slog (stdlib, Go 1.21+) with JSON handler.
  • go.opentelemetry.io/otel + auto-instrumentation.
  • prometheus/client_golang.

Rust

  • tracing + tracing-subscriber with JSON formatter.
  • opentelemetry-otlp.
  • prometheus crate.

Anti-patterns

  • "Log everything, we'll figure it out later" — the noise hides the signal you need.
  • Traces without sampling — you'll drown; sample intelligently (head-based at edges, tail-based for errors).
  • Metrics where logs would do — counting "user clicked button" 1M times/day is cheaper as a metric than a log.
  • Logs where metrics would do — "latency: 247ms" as a log line is wasting money; it's a histogram.
  • Alerts on everything — page only on symptoms that hurt users, not causes.

Smells

  • A single log line has more than ~10 fields — probably two events glued together.
  • You use grep to find things — you should have a field + dashboard.
  • Error messages are generic ("an error occurred") — they cost you the 2am minutes.
  • console.log in prod code — belongs in a logger, tagged and leveled.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.