observability
Structured logging and OpenTelemetry distributed tracing, incl. log-trace-metric correlation. NOT for metrics/dashboards/alerts (belong to monitoring) and NOT for Helm health probes.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 8
- Forks
- 5
01 前言 Front Matter
- docs
- { "status": "reviewed", "updated": 1785974400000, "source_sha": "3c7676ebd024" }
- name
- observability
- owner
- swarmery-core
- version
- 1.0.0
- description
- Structured logging and OpenTelemetry distributed tracing, incl. log-trace-metric correlation. NOT for metrics/dashboards/alerts (belong to monitoring) and NOT for Helm health probes.
02 资源文件 2
- 参考文档resources/checks-and-failure-modes.md5.5 KB
- 参考文档resources/logging-and-tracing-patterns.md6.3 KB
03 SKILL.md 正文
Purpose
Instrument the project's services with structured logging and OpenTelemetry distributed tracing, and provide the patterns for correlating logs, traces, and metrics when diagnosing issues. Code-level instrumentation only — what to log, how to propagate trace context, how to correlate signals. Placeholders <mainApp> and <device> resolve from project.json.
Rules
- Logs are JSON with required fields
timestamp,level,service,message— plustrace_id/span_idwhen tracing is active. - NEVER log PII, passwords, tokens, API keys, or secrets; review every context field.
- High-frequency per-message events (several Hz per device) log at DEBUG, never INFO; INFO is for summaries and state changes.
- Span names are meaningful with domain-specific attribute keys (
device.id, notid); no unbounded span attributes (request bodies, user input). - Propagate trace context at every service boundary (WebSocket, HTTP) — a missing injection breaks the trace and loses correlation.
- Logging and tracing only: metrics, dashboards, and alerts belong to
monitoring; Helm health probes and log routing belong to the project's infra pack skills.
Resources
- Read
resources/logging-and-tracing-patterns.mdwhen instrumenting — the log format, Python/TypeScript logger wrappers, OTel span code, context propagation, the five-step correlation path, inputs/outputs and length budgets. - Read
resources/checks-and-failure-modes.mdbefore returning or when something misbehaves — self-check list, common mistakes, escalation triggers, worked examples, failure modes, related skills.
How to use
What it does
Adds structured logging and OpenTelemetry tracing to a service and shows how to follow one request across services: which fields every log line carries, how to name spans, how to pass trace context over a boundary, and how to jump from a slow trace to the log lines explaining it.
When to use it
- Adding logging to a service and wanting a JSON format a log backend can parse.
- Instrumenting with OTel spans, or a trace breaks mid-flow and needs context propagation.
- Going from a trace ID to the log lines for that same request.
- Reviewing log statements for leaked personal data, tokens, or secrets. (Metric/dashboard/alert work starts with
monitoringinstead.)
How to invoke
Skill(skill: "core:observability")
Invoke before writing instrumentation code. Required inputs: target service and instrumentation goal (logging, tracing, or correlation). Optional: your existing logger setup, so it is extended rather than replaced.
Worked example
Skill(skill: "core:observability")
Add structured logging to the order submit route in apps/<mainApp>.
The skill defines the JSON log shape (timestamp, level, service, message, plus trace_id and domain fields), writes a typed logger wrapper, and adds logger.info / logger.warn calls to the orders/line-items route — request received, not found, submitted. You end up with parseable logs carrying an order ID and no personal data, plus a trace ID you can paste into log search.
04 同仓库更多 Skills
short-desc
Too short.
no-frontmatter
暂无简介
global-skill
Fixture global skill (minimal user-scope shape, format doc §2.3).
documented-skill
Fixture skill whose usage guide deliberately omits the Worked example subsection.
z
NOT auto-discovered — only skills/ is scanned for plugins (§2.2).
y
Plugin skill y from toolpack — stored as "toolpack:y".