# Observability

> Adds OpenTelemetry-style tracing and structured logging around fn(args, deps) boundaries without leaking PII. Use this skill when instrumenting TypeScript services, adding spans/logs/metrics, or correlating request failures. Do not use when/for debugging a single local failure without telemetry design (use debugging-methodology) or HTTP envelope design alone (use api-design).

- Skill: `jagreehal/observability` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jagreehal/observability`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/observability/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/observability

---


# Functions + OpenTelemetry

## Critical rules

- Observability is an observer: wrap with `trace()`; business functions stay telemetry-blind and return Results.
- Structured JSON logs only (Pino) — never string interpolation. Redact sensitive fields in logs and span attributes.
- Use OpenTelemetry semantic attribute names (`user.id`, not `userId`).
- Map Result ok/err to span status. Correlate logs with `traceId`/`spanId`. Prefer one canonical wide event per request.
- Tests must not change when tracing is off (`trace()` is a no-op).
- Before wrapping or configuring, read [references/patterns.md](references/patterns.md) and [references/setup.md](references/setup.md).

## Workflow

1. Init autotel + Pino with redaction and optional attribute filter — see [references/setup.md](references/setup.md).
2. Wrap `fn(args, deps)` with `trace((ctx) => async (args, deps) => ...)`.
3. Set semantic attributes; map Result to span status; never put retry/branch decisions in the core function for telemetry.
4. Ensure logs include trace/span IDs; enable canonical wide events for request roots when useful.
5. Use `track()` for point-in-time business events; keep existing unit tests unchanged.

## Resources

- [references/patterns.md](references/patterns.md) — structured logs, trace wrap, semantics, redaction, wide events. Read when instrumenting.
- [references/setup.md](references/setup.md) — init, backends, track vs trace, test no-op. Read when bootstrapping.

## Validation

- [ ] Structured fields, not string interpolation
- [ ] Tracing in wrapper only; function stays blind
- [ ] OTel semantic attribute names
- [ ] PII redacted in logs and spans
- [ ] Result maps to span status; logs carry trace/span IDs
- [ ] Existing tests pass unchanged

## Constraints

- Not a substitute for proper Result errors. Avoid hot loops where span overhead dominates.
- Related: `result-types`, `fn-args-deps`, `api-design`, `resilience`.