Index of every page on this site: llms.txt
All skills
Run it yourself

Instruments a feature so on-call can tell that it broke, where time went, and why, using logs, metrics, and traces, and designs symptom alerts. Includes a measured performance loop and caching rules. Use when adding logging, logs, structured logs, metrics, tracing, OpenTelemetry, spans, a correlation or request ID, alerts, an SLO, or on-call, when asking how we will know it broke, when instrumenting a feature, endpoint, job, or integration, or when the user mentions performance, a slow endpoint, latency, profiling, optimize, or caching. Not for diagnosing a live incident - use the debug skill where installed; not for creating alerts or dashboards in a specific backend - use that backend's skill; not for database query tuning - use database.

  • 5 files
  • 19.1 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/avik-creator/agent-skills/observability

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈191 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈3.6k more on demand in 4 files.

Description uses 9.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈766 characters, or 9.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Observability

Write the telemetry with the feature. A signal that answers no on-call question is noise. Creating or changing an alert, a dashboard, or a saved view in a real backend is that backend's skill, and only after a yes. Why: shared monitoring is outward-facing.

Quick start

  1. Write 2–4 questions on-call will ask. Map every signal to one of them.
  2. Pick the signal: metrics say that something is wrong, traces say where, logs say why.
  3. Log, count, and trace as below. Detail is in instrumentation.md.
  4. For a new alert, follow alerts.md; for an SLO behind it, slo.md.
  5. In staging, or a local run with the same telemetry, cause a failure and find it from the telemetry alone.
  6. A measured slowness follows performance.md. Do not start one from a guess.

On-call questions

Feature: checkout payment retry
1. What fraction succeed on the first attempt, and what fraction after a retry?
2. When one fails for good, why (provider error, timeout, validation)?
3. Is the provider slower than usual?

If you cannot name the questions, do not add telemetry yet.

Logs

Log an event with a stable name and structured fields, not a sentence with the values interpolated in. Levels:

Level When On-call
error An invariant broke; someone may have to act Investigate
warn Degraded, and the code handled it Watch the trend
info A business event (order placed, job finished) None
debug Diagnostic detail Off in production

Generate or accept a correlation id at the boundary and pass it on every log line, outbound call, and queue message. When more than one entry point writes the same log, stamp which one started the run, next to the correlation id. Allowlist the fields. No secrets, tokens, bodies, auth headers, or direct identifiers (name, email, phone); an opaque user or tenant id is a field, as the security skill's privacy rules say.

The security skill's audit events are info (or warn on failure): login success and failure, role and permission changes, data export, data delete.

Metrics and traces

RED (rate, errors, duration) on each endpoint and each dependency. USE (utilization, saturation, errors) on a resource such as a queue, a pool, or a host. Labels come from a bounded set: route template, status class (5xx, not 503), dependency name. A user id, tenant id, request id, URL, or error text is a log field, not a label. Why: each new label value is a new series.

Record latency as a histogram and read it as a percentile. An average hides the slow tail.

Trace with OpenTelemetry. Propagate W3C traceparent across HTTP, queues, and async work. A manual span wraps one meaningful unit of work. No direct identifiers or tokens in span attributes. Sampling is a choice of head-based or tail-based, described in instrumentation.md, not a default rate.

SDK setup and exporters follow the language's OpenTelemetry docs; for Go logging (log/slog) see the go skill.

Verify

In staging, force the failure the questions are about. Find that one request by its correlation id, see the metric move, and see the trace cross the hop. Do this before calling the feature done. Why: telemetry is code, and it can be wrong.

Hand over

  • The on-call questions, and which signal answers each.
  • What you induced, and where it showed up.
  • Could improve: a missing RED series, a label with unbounded values, an alert with no runbook. Propose it, and apply it after a yes. A change inside a monitoring backend waits for that backend's skill and a yes.

Replies

Talk to the user in simple English: short sentences, everyday words, and a technical term only where it is needed, explained the first time it appears.

References

File Read when
instrumentation.md adding a log line, a metric, or a span
alerts.md writing or changing an alert
slo.md defining an SLI, SLO or error budget, or a burn-rate alert
performance.md a measured or reported slowness, or a stated target

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at a0324a3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 3 weeks ago

README badge

README badge for avik-creator/agent-skills/observability