其他技能
common-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.
HoangNguyen0403 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add HoangNguyen0403/agent-skills-standard --skill common-observability技能说明
name: common-observability description: 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. metadata: triggers: files: - "/*.service.ts" - "/.handler.ts" - "**/.middleware.ts" - "/*.interceptor.ts" - "/.go" - "**/.java" - "/*.kt" - "/*.py" keywords: - logging - tracing - metrics - opentelemetry - observability - slo
Common Observability Standards
Priority: P1 (HIGH)
Logging & Tracing
- JSON Logs: Always emit JSON structured logs. Never plain-text in prod.
- Correlation: Extract
X-Request-Idortraceparent. Attach to async context. - Tracing: Use OpenTelemetry. Propagate W3C
traceparent. - Spans: Name spans like
<HTTP_METHOD> <route>(GET /users/:id).
See implementation examples for structured logger setup with Pino.
Metrics
- Required: Request rate, Error rate, Latency histogram (p50/p95/p99), Saturation.
- SLOs: Alert on SLO burn rates, not raw threshold spikes.
Instrumentation Workflow
- Define the operation and route-normalized span name before adding code.
- Propagate request/trace context across every async or service boundary.
- Log one structured event with correlation fields; redact secrets and request bodies.
- Add RED metrics with route-safe labels, then define an SLO and burn-rate alert.
- Exercise a success and failure path; confirm spans close and IDs join logs to traces.
Anti-Patterns
- Console.log: not use in prod; use structured logger (
pino,zap). - PII in Logs: Never log tokens, passwords, or full request bodies.
- Dynamic Span Names:
GET /users/123causes cardinality explosion. UseGET /users/:id. - Missing Cleanup: Always end tracing spans.
References
- Observability Data Formats