autotel

Use this skill when instrumenting AI/LLM/agent code with OpenTelemetry GenAI semantic conventions — traceGenAI() spans, token usage and cost, gen_ai.* attributes, GenAI metric views, content/evaluation events, the Vercel AI SDK bridge, or the agent identity/delegation/policy/audit governance layer. This is the canonical home for everything GenAI in autotel (the core `autotel` package is AI-free).

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.

Query OpenTelemetry telemetry (traces, metrics, logs, LLM analytics) via the autotel CLI. Use when the user asks about a production issue, slow request, error spike, expensive LLM call, or any "what is happening in my service" question. Each command returns one JSON document on stdout — parse it and answer from the data.

OpenTelemetry instrumentation for MCP (Model Context Protocol). instrumentMCPServer, instrumentMCPClient; W3C trace context via _meta; tools, resources, prompts. Security observability: annotation hints, payload-size & char-budget signals, pluggable prompt-injection classifier, spotlighting.

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.

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.

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.

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.

Create a new autotel framework adapter package — e.g. autotel-elysia, autotel-fastify, autotel-h3. Adapters wire request lifecycle, useLogger(), withAutotel handler wrapping, and async-safe context propagation through AsyncLocalStorage. Covers source layout, exports, tests, package.json setup, and registration in the monorepo.

Ship a new vendor exporter for autotel — for backends that need a custom envelope shape on top of OTLP (Sentry, Axiom, HyperDX, Better Stack, PostHog, …) or a non-OTLP transport entirely. Covers retry, batching, error handling, auth resolution, and cross-runtime support (Node + Workers + edge).

Auto-instrument a third-party library (Drizzle, Mongoose, Redis, Kysely, Prisma, BullMQ, …) so every call produces an OpenTelemetry-spec-compliant span. Covers operation naming, attribute conventions (db.system, messaging.system, http.*, rpc.*), error capture, sensitive-statement redaction, package layout, and tests.

Use when instrumenting with trace/span/track, reviewing code for logging and observability patterns, converting console.log to wide events, adding structured errors, setting up canonical log lines, configuring init(), adding subscribers, or working in the autotel monorepo.

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.

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.

Standalone OTLP receiver with a Svelte web UI for local-dev observability. Use when a developer wants to see OpenTelemetry traces, logs, metrics, and service maps streaming from a running app without setting up Jaeger/Tempo/Prometheus — either as a CLI dashboard or an embedded `<autotel-devtools>` widget.

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.

Framework adapters for autotel that add request-scoped logging, tracing, and utility helpers for Next.js, Nitro, Cloudflare Workers, Hono, and TanStack Start.

OpenTelemetry instrumentation for AWS services (Lambda, SDK v3 clients, S3, DynamoDB, SQS, SNS, Kinesis, Step Functions, X-Ray) built on top of autotel.

Vendor preset configs for autotel that produce a ready-to-use AutotelConfig for Honeycomb, Datadog, Google Cloud, and Grafana Cloud with best-practice defaults already baked in.

Use this skill when running autotel CLI commands to set up, configure, or extend OpenTelemetry instrumentation in a Node.js project — including init, doctor, add, and codemod trace.

OpenTelemetry for Cloudflare Workers. Instrument handlers, bindings (KV, R2, D1, AI, Vectorize, Queues, Durable Objects), and global fetch/cache. Multiple API styles for compatibility.

Use this skill when adding OpenTelemetry tracing to a Drizzle ORM database instance — the only autotel instrumentation package needed for Drizzle, since no official OTel package exists for it.

OpenTelemetry for edge runtimes (Cloudflare Workers, Vercel Edge, Deno). trace(), span(), instrument(); sampling, events, logger. Bundle-size optimized; no Node.js APIs.

OpenTelemetry middleware for Hono. Add otel() middleware to trace HTTP requests with semantic attributes, capture headers, and track request metrics.

MCP server AI agents connect to for investigating OpenTelemetry telemetry. Use when an agent needs to query traces, metrics, or logs from Jaeger, Tempo, Prometheus, Loki, or a built-in OTLP collector — including LLM-specific analytics (USD cost, token usage, per-model stats).

Use this skill when adding OpenTelemetry tracing to a Mongoose 8+ application — covers instrumentMongoose(), query text capture, automatic PII redaction, and Schema hook instrumentation.

Playwright fixture and reporter that create one OTel span per test and inject W3C trace context into API requests, linking e2e tests to server-side traces.

OpenTelemetry instrumentation plugins for BigQuery, Kafka, and RabbitMQ — covering libraries with no official OTel support (BigQuery) or where the official package lacks critical DX (Kafka/RabbitMQ processing spans, batch lineage, correlation IDs).

Bridge that converts OpenTelemetry (Autotel) spans to Sentry transactions/spans and propagates sentry-trace/baggage headers, linking OTel traces to Sentry performance monitoring and error tracking.

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

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

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

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

Event subscribers for autotel. PostHog, Mixpanel, Amplitude, Segment, Webhook, Slack. Configure in init() subscribers; use track() or Event from autotel. Import from autotel-subscribers/posthog etc.

OpenTelemetry for TanStack Start. Trace server functions, route loaders, middleware, and request handlers. Supports zero-config, middleware-based, and explicit wrapper patterns.

Use this skill when integrating the autotel-terminal dashboard into a Node.js app or running it as a standalone OTLP receiver — covers renderTerminal(), StreamingSpanProcessor, the CLI, and the AI assistant configuration.

Use this skill when adding OpenTelemetry tracing to Vitest tests — gives each test a parent span so all instrumented code becomes filterable child spans in your OTLP backend.

Use this skill when adding distributed tracing to a browser application — covers lean mode (traceparent header injection, ~1.6KB), full mode (real OTel spans, Web Vitals, error capture), privacy controls, and SSR-safe setup.

Common autotel mistakes and how to fix them. Wrong init patterns, manual span lifecycle, scattered console.log, generic Error throws, missing emitNow(), wrong import paths, secrets in attributes, barrel re-exports. Use when reviewing code or debugging instrumentation issues.

Complete autotel API reference: trace(), span(), instrument(), getRequestLogger(), createStructuredError(), parseError(), track(), init(). Import paths, function signatures, factory vs direct pattern, name inference. Use as the primary reference when writing autotel code.