Skip to content
Skills Library
DevOps & cloud · Building & coding

observability

/observability

Use when adding logging, metrics, or tracing to code, or designing how a service is monitored. Covers the three pillars, structured logging, what to measure (RED/ USE), useful alerts, and the SLO mindset — so failures are debuggable after the fact.

Repository
md-files ↗
Licence
MIT
Last repository change
03.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/forge-lineage.py, scripts/forge-provenance.py, scripts/forge-receipts.py, scripts/forge-trajectory-evals.py

What it does and when to use it

Use when adding logging, metrics, or tracing to code, or designing how a service is monitored. Covers the three pillars, structured logging, what to measure (RED/ USE), useful alerts, and the SLO mindset — so failures are debuggable after the fact.

Original author description

Use when adding logging, metrics, or tracing to code, or designing how a service is monitored. Covers the three pillars, structured logging, what to measure (RED/ USE), useful alerts, and the SLO mindset — so failures are debuggable after the fact.

How it works

  1. The three pillars
  2. Structured logging
  3. What to measure
  4. Alerting
  5. Instrumenting new code
  6. Forge receipts
  7. Offline lineage verification
  8. Signed trace and provenance bridge
Original SKILL.md headings · 103 lines, 626 words
SKILL.md preview
---
name: observability
description: >-
  Use when adding logging, metrics, or tracing to code, or designing how a service
  is monitored. Covers the three pillars, structured logging, what to measure (RED/
  USE), useful alerts, and the SLO mindset — so failures are debuggable after the
  fact.
---

# Observability

Observability is the ability to understand a system's internal state from its outputs.
You instrument so that when something breaks at 3 a.m., the signals already exist to
explain it — you can't add a log line after the incident.

## The three pillars

- **Logs** — discrete events with context. Use for the "what exactly happened" of a
  specific request.
- **Metrics** — aggregated numbers over time. Use for trends, rates, and alerting.
  Cheap to store, fast to query.
- **Traces** — the path of one request across services. Use to find *where* latency or
  errors originate in a distributed call.

Connect them: put a trace/request ID on every log line and metric exemplar so you can
pivot from a metric spike to the traces to the logs.

## Structured logging

Log structured key–value pairs (JSON), not interpolated prose — so logs are queryable.
Include request ID, user/tenant (non-PII), operation, duration, and outcome. Log at the
right level: ERROR = needs attention, WARN = unusual but handled, INFO = significant
state change, DEBUG = diagnostic detail. **Never log secrets, tokens, or PII.**

```text
log.info("payment.captured", order_id=o.id, amount=o.total, request_id=ctx.rid, latency_ms=dt)
```

## What to measure

- **RED** (request-driven services): **R**ate, **E**rrors, **D**uration per endpoint.
- **USE** (resources): **U**tilization, **S**aturation, **E**rrors per resource.
- Business signals that matter (signups, checkouts) alongside system signals.

Track distributions (p50/p95/p99), not just averages — the tail is where users feel pain.

## Alerting

Alert on **symptoms users feel** (error rate, latency SLO breach, saturation), not every
internal cause. Every alert must be actionable and point toward a runbook — a pager that
cries wolf gets ignored. Define SLOs (e.g. 99.9% of requests < 300ms) and alert on burn
rate against the error budget.

## Instrumenting new code

For each critical path: emit a metric (rate/error/duration), a span if it crosses a
service boundary, and structured logs at the decision points and failures. Make the
failure path as observable as the success path — that's the part you'll need most.

## Forge receipts

For orchestration evidence, use the bundled `scripts/forge-receipts.py` store rather than
free-form logs. It writes append-only, schema-versioned JSONL with monotonic sequences,
idempotency keys, causation, W3C trace context, and privacy-safe attributes. Read the
[receipt guide](../../../docs/receipts.md) before enabling OTLP export.

## Offline lineage verification

For durable runtime evidence, export from the canonical SQLite history with
`scripts/forge-lineage.py`. The verifier binds scheduling events, effect attempts, lease
generations, adapter revisions, provider references, retries, dead letters, and optional
policy receipts into a deterministic manifest. It is offline-only and fails closed on a
missing parent, digest mismatch, conflicting provider reference, or stale generation:

```bash
python3 scripts/forge-lineage.py export \
  --db .forge/runtime.sqlite3 --receipts .forge/receipts.jsonl \
  --output .forge/lineage.json
python3 scripts/forge-lineage.py verify --manifest .forge/lineage.json
```

Lineage is evidence, not a replacement for canonical runtime history and not an exactly-once
claim. Keep provider bodies, prompts, credentials, and tool content out of the manifest.

## Signed trace and provenance bridge

For a portable, authenticated evidence package, use `scripts/forge-provenance.py`. It composes
the verified lineage manifest, derives stable W3C trace/span identities from Forge IDs, maps
workflow, agent, tool, effect, wait, receipt, and bounded GenAI cost fields to the pinned
`forge-otel-1` convention, and signs an in-toto-shaped statement for offline verification:

```bash
python3 scripts/forge-provenance.py export \
  --db .forge/runtime.sqlite3 \
  --source-revision git:HEAD \
  --policy-revision policy-v1 \
  --key-id forge-local-2026 \
  --key-file .forge/keys/forge-local-2026.key \
  --trust-policy .forge/keys/trust-policy.json \
  --output .forge/provenance.json
python3 scripts/forge-provenance.py verify \
  --bundle .forge/provenance.json \
  --trust-policy .forge/keys/trust-policy.json
```

The default bundle contains digests and bounded references only. Raw prompts, credentials,
tool arguments/results, and provider bodies are never exported implicitly. HMAC key material
must stay outside bundles and source control; see [`docs/provenance.md`](../../../docs/provenance.md)
for rotation, retention, redaction, and incident-response rules. Invalid W3C context is rejected
so a caller can safely retry without the untrusted header and derive a new trace.
Files in this package (5)
  • SKILL.md 5 KB
  • scripts/forge-lineage.py 39 KB
  • scripts/forge-provenance.py 52 KB
  • scripts/forge-receipts.py 18 KB
  • scripts/forge-trajectory-evals.py 36 KB

Versions

RepositoryScoreLicence
This page · alisinadevelo/md-files100MIT
maragudk/fabrik100MIT
matteocodogno/wellforge100MIT
iuliandita/skills100MIT
ctxpipe-ai/ctxpipe100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
wrongstack/wrongstack100MIT
nvidia/ai-factory-operations-agent100Apache-2.0

Database snapshot: 13.11.2026 · package version def9234cda04 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100monitoring-plan
    Use when the user needs observability for a service or feature: a monitoring plan, metrics, alerts, dashboards, SLOs, logging, or tracing.
  • 100ops
    Post-deploy observability for production services — structured logging, RED metrics + Prometheus, Grafana dashboards, SLO-based alerting. Use when setting up monitoring or instrumenting a live service. Trigger on "add logging", "metrics", "dashboard", "alerting",…
  • 100common-observability
    Enforce structured JSON logging, OpenTelemetry distributed tracing, and RED metrics across backend services. Use when adding request correlation, setting up tracing spans, defining SLO burn-rate alerts, or instrumenting middleware.
  • 100monitoring-observability
    OpenTelemetry, structured logging, distributed tracing, alerting, and dashboards. Use when instrumenting services, designing logs/traces/metrics, defining SLOs and alerts, or debugging production behavior from telemetry.
  • 100python-observability
    Python observability patterns including structured logging, metrics, and distributed tracing. Use when adding logging, implementing metrics collection, setting up tracing, or debugging production systems.
  • 90observability-designer
    Use when adding observability to a new service, refactoring noisy alerting, or designing a monitoring strategy. Covers the three pillars (metrics/logs/traces), golden-signal dashboards, and alert-noise reduction. For SLO/error-budget math specifically, route to `slo-architect` instead.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.