Observability Modeling
Concept of the skill
Designing telemetry semantics before or during implementation — logs, metrics, traces, events, spans, attributes, correlation IDs, SLOs, alert signals, and the diagnostic questions telemetry must answer.
Coverage
Design telemetry semantics that make systems diagnosable. Covers diagnostic questions, logs, metrics, traces, spans, events, attributes, correlation IDs, SLOs, alert signals, cardinality, privacy, sampling, and contract-level observability requirements.
Philosophy of the skill
Observability starts with questions, not tools. "Can we answer why this order failed to sync?" is a better design input than "add logs." Tool setup without a telemetry model produces noisy data and weak diagnosis.
Instrument boundaries, state changes, and decisions. Avoid high-cardinality or sensitive fields unless the operational value justifies the risk.
Method
- List diagnostic questions the system must answer.
- Map each question to required signals: log, metric, trace, event, or derived view.
- Define correlation identifiers across boundaries.
- Name span/event attributes with stable semantics and cardinality limits.
- Add SLOs and alert signals only for user or business impact.
- Define privacy redaction and sampling rules.
- Verify that failures can be reconstructed from emitted signals.
Evals
This skill ships a comprehension-eval artifact at examples/evals/observability-modeling.json. The checklist below is the authoring gate for telemetry-semantics decisions; the eval file is the grader surface.
Verification
Do NOT Use When
| Use instead |
When |
error-tracking |
You need error tracker setup, redaction, source maps, or issue triage. |
event-contract-design |
You need a business/domain event envelope, schema, topic, replay, or consumer compatibility contract. |
performance-engineering |
You need to profile and optimize latency, throughput, or resource use. |
debugging |
There is already a failing incident or reproducible bug. |
testing-strategy |
You need pre-runtime test coverage design. |
Skill Graph context
Classification
- Subject:
data-engineering (also: quality-assurance)
- Public:
true
- Domain:
engineering/observability
- Scope: Designing telemetry semantics before or during implementation — logs, metrics, traces, events, spans, attributes, correlation IDs, SLOs, alert signals, and the diagnostic questions telemetry must answer. Portable across any instrumented system; principle-grounded, not repo-bound. Excludes domain/business event contracts (event-contract-design), configuring an error tracker alone (error-tracking), performance optimization (performance-engineering), and debugging a current incident (debugging).
When to use
- design telemetry for this ingestion pipeline so failures can be diagnosed later
- which logs, metrics, spans, and correlation IDs should this interface contract require?
- model observability for a background job before adding alerts
- turn these diagnostic questions into events and metrics
Not for
- set up Sentry error tracking for this app
- profile and optimize a slow endpoint
- debug the current production incident
- write application tests for this feature
Related skills
- Verify with:
error-tracking, debugging, performance-budgets
- Related:
system-interface-contracts, testing-strategy, error-tracking, performance-engineering, event-contract-design, debugging, semantics
Keywords
observability modeling, telemetry design, logs metrics traces, SLO, spans, correlation id, diagnostic events, alert design, instrumentation model
1---2name: observability-modeling3description: Use when designing telemetry semantics before or during implementation: logs, metrics, traces, events, spans, attributes, correlation IDs, SLOs, alert signals, and diagnostic questions. Do NOT use for domain/business event contracts (use `event-contract-design`), configuring an error tracker alone (use `error-tracking`), performance optimization (use `performance-engineering`), or debugging a current incident (use `debugging`). Do NOT use for set up Sentry error tracking for this app. Do NOT use for profile and optimize a slow endpoint. Do NOT use for debug the current production incident. Do NOT use for write application tests for this feature.4license: MIT5---6# Observability Modeling78## Concept of the skill910Designing telemetry semantics before or during implementation — logs, metrics, traces, events, spans, attributes, correlation IDs, SLOs, alert signals, and the diagnostic questions telemetry must answer.1112## Coverage1314Design telemetry semantics that make systems diagnosable. Covers diagnostic questions, logs, metrics, traces, spans, events, attributes, correlation IDs, SLOs, alert signals, cardinality, privacy, sampling, and contract-level observability requirements.1516## Philosophy of the skill17Observability starts with questions, not tools. "Can we answer why this order failed to sync?" is a better design input than "add logs." Tool setup without a telemetry model produces noisy data and weak diagnosis.1819Instrument boundaries, state changes, and decisions. Avoid high-cardinality or sensitive fields unless the operational value justifies the risk.2021## Method22231. List diagnostic questions the system must answer.242. Map each question to required signals: log, metric, trace, event, or derived view.253. Define correlation identifiers across boundaries.264. Name span/event attributes with stable semantics and cardinality limits.275. Add SLOs and alert signals only for user or business impact.286. Define privacy redaction and sampling rules.297. Verify that failures can be reconstructed from emitted signals.3031## Evals3233This skill ships a comprehension-eval artifact at [`examples/evals/observability-modeling.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/observability-modeling.json). The checklist below is the authoring gate for telemetry-semantics decisions; the eval file is the grader surface.3435## Verification3637- [ ] Telemetry answers named diagnostic questions38- [ ] Correlation IDs cross async and external boundaries39- [ ] Event and metric names use stable domain language40- [ ] High-cardinality attributes are avoided or justified41- [ ] Sensitive data is redacted before emission42- [ ] Alerts map to actionable symptoms, not raw noise43- [ ] A realistic failure can be reconstructed from the proposed signals4445## Do NOT Use When4647| Use instead | When |48|---|---|49| `error-tracking` | You need error tracker setup, redaction, source maps, or issue triage. |50| `event-contract-design` | You need a business/domain event envelope, schema, topic, replay, or consumer compatibility contract. |51| `performance-engineering` | You need to profile and optimize latency, throughput, or resource use. |52| `debugging` | There is already a failing incident or reproducible bug. |53| `testing-strategy` | You need pre-runtime test coverage design. |5455## Skill Graph context5657<!-- skill-graph-context:start (generated — do not edit by hand) -->5859**Classification**60- Subject: `data-engineering` (also: `quality-assurance`)61- Public: `true`62- Domain: `engineering/observability`63- Scope: Designing telemetry semantics before or during implementation — logs, metrics, traces, events, spans, attributes, correlation IDs, SLOs, alert signals, and the diagnostic questions telemetry must answer. Portable across any instrumented system; principle-grounded, not repo-bound. Excludes domain/business event contracts (event-contract-design), configuring an error tracker alone (error-tracking), performance optimization (performance-engineering), and debugging a current incident (debugging).6465**When to use**66- design telemetry for this ingestion pipeline so failures can be diagnosed later67- which logs, metrics, spans, and correlation IDs should this interface contract require?68- model observability for a background job before adding alerts69- turn these diagnostic questions into events and metrics7071**Not for**72- set up Sentry error tracking for this app73- profile and optimize a slow endpoint74- debug the current production incident75- write application tests for this feature7677**Related skills**78- Verify with: `error-tracking`, `debugging`, `performance-budgets`79- Related: `system-interface-contracts`, `testing-strategy`, `error-tracking`, `performance-engineering`, `event-contract-design`, `debugging`, `semantics`8081**Keywords**82- `observability modeling`, `telemetry design`, `logs metrics traces`, `SLO`, `spans`, `correlation id`, `diagnostic events`, `alert design`, `instrumentation model`8384<!-- skill-graph-context:end -->
jacob-balslev