Skills12History

analyze-traces

Analyze OpenTelemetry traces and structured logs from a running autotel service to debug errors, investigate latency, follow requests across services, and surface cardinality / attribute hygiene problems. Works with traces from any OTLP backend (Honeycomb, Grafana Tempo, Datadog, Jaeger, Sentry, Axiom, HyperDX, …) plus the local `.autotel/spans/` dump and `InMemorySpanExporter` in tests.

181 lines

autotel-core

When to use trace vs span vs request logger vs events in Autotel. Init once at startup, package exports (autotel, autotel/event, autotel/testing). Use for setup and choosing the right API.

160 lines

autotel-events

track(), Event API, subscribers (e.g. PostHog). Configure subscribers in init(); use track() or Event for product/analytics events.

85 lines

autotel-frameworks

Hono, Fastify, TanStack Start, Cloudflare Workers. Middleware and init; getRequestLogger() in handlers. Load when adding Autotel to a web framework.

91 lines

autotel-instrumentation

trace(), span(), instrument(), init(). Factory vs direct pattern, name inference. Sync init; use node-require for optional deps. Load when wrapping handlers or functions with spans.

146 lines

autotel-request-logging

getRequestLogger(), set(), info/warn/error, emitNow(). One snapshot per request; requires active span. Use when adding request-scoped context or replacing scattered console.log.

95 lines

autotel-structured-errors

createStructuredError, parseError, recordStructuredError. API errors with message, why, fix, link; client parsing for UI. Use in API routes and client catch blocks.

126 lines

build-audit-trails

Build or review tamper-aware audit trails on top of OpenTelemetry spans using autotel and the autotel-audit package (`withAudit`, `setAuditAttributes`, `forceKeepAuditEvent`). Covers what counts as auditable, the audit-only span discipline, sampling bypass, HMAC and hash-chain signing with tamper detection, denial logging, redaction, retention, GDPR right-to-erasure via crypto-shredding, separation from operational telemetry, testing audit spans, backend-agnostic audit queries, a production-readiness checklist, and framework wiring (Next.js, Nuxt, Nitro, NestJS, Express, Fastify, Hono, Cloudflare Workers, AWS Lambda, standalone). Use it to design new audit trails or review existing ones for GDPR, HIPAA, SOC 2, PCI-DSS, ISO 27001, SOX, and GxP compliance.

461 lines

debug-missing-spans

Troubleshoot when expected OpenTelemetry spans don't reach the backend. Walks the chain top-to-bottom — code → SDK init → processor → exporter → network → backend ingest — with concrete tests at each step. Covers head sampling, ctx.waitUntil drops on Cloudflare, init-order races, runtime detection failures, propagation breaks, exporter auth errors, and silent ratelimits.

251 lines

migrate-to-autotel

Migrate an existing observability setup to autotel. Handles raw @opentelemetry/sdk-node, Sentry tracer (`@sentry/node`), Datadog APM (`dd-trace`), New Relic agent (`newrelic`), Honeycomb Beelines, and OpenTracing / OpenCensus. Preserves trace fidelity (no gap in dashboards during cutover), maps vendor-specific span attributes to OTel semantic conventions, and runs both stacks side-by-side during the cutover window.

270 lines

review-otel-patterns

Review TypeScript/JavaScript code for OpenTelemetry instrumentation patterns and guide adoption of autotel. Covers Next.js, Nuxt, Nitro, TanStack Start, SvelteKit, NestJS, Express, Hono, Fastify, Elysia, Cloudflare Workers, AWS Lambda, edge runtimes, and standalone Node. Detects unstructured tracing, missing span attributes, manual exporter setup, broken context propagation, exposed PII, and ad-hoc error handling. Covers spans, metrics, logs, structured errors, the autotel processor pipeline (tail-sampling, attribute redaction, span-name normalisation, filtering, baggage), built-in enrichers (user agent, geo, request size) and custom `defineEnricher`, `defineWorkerFetch` for Cloudflare async drains, multi-vendor OTLP backends (Honeycomb, Datadog, Grafana Cloud, Sentry, Axiom, HyperDX), `composeSpanProcessors` / `composeSubscribers` / `composePostProcessors` for pipelines, AI SDK observability with gen-ai semantic conventions, and end-to-end OTLP testing.

539 lines

tune-sampling

Choose a sampling strategy for an autotel-instrumented service. Covers head sampling (per-span-kind rates, parent-based, ratio), tail sampling (keep errors, slow, AI-aware, debug-headers), cost vs cardinality tradeoffs, and the math for picking rates that hit a target spans/second budget. Includes recipes for low-volume admin services, high-volume APIs, AI agents, and Cloudflare Workers.

216 lines