opentelemetry-observability-architect

Implements OpenTelemetry tracing, metrics, and trace-correlated logging for Node.js Fastify applications.

1|Updated May 4, 2026
One-click install
npx skills add https://github.com/Scardubu/SwarmXQ --skill opentelemetry-observability-architect-scardubu
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: opentelemetry-observability-architect
Source: https://github.com/Scardubu/SwarmXQ/tree/main/.ai/skills/opentelemetry-observability-architect
Command: npx skills add https://github.com/Scardubu/SwarmXQ --skill opentelemetry-observability-architect-scardubu

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @opentelemetry/sdk-node, @opentelemetry/api, @opentelemetry/auto-instrumentations-node, @opentelemetry/exporter-trace-otlp-http, @opentelemetry/exporter-metrics-otlp-http, @prisma/instrumentation, @fastify/otel, pino.

What problem does it solve? Node.js services often run blind in production: slow Prisma queries, failing BullMQ jobs, and scattered logs with no way to connect them to a single request. This Skill generates a complete OpenTelemetry setup so every request, query, and job is traced, measured, and logged with correlation IDs. ## Core Features & Use Cases - SDK Initialization & Auto-Instrumentation: Generates instrumentation.ts with NodeSDK, OTLP trace and metric exporters, and auto-instrumentation for Fastify, Prisma, and HTTP, enforcing the critical rule that OTel loads before all other imports. - Custom Spans & Queue Propagation: Wraps business logic in named spans with attributes and error recording, and propagates trace context from BullMQ producers to workers. - RED Metrics & Structured Logging: Configures rate/error/duration histograms, observable gauges for active jobs, and a Pino logger that injects traceId and spanId into every log line. - Use Case: You have a Fastify API backed by Prisma and BullMQ and cannot tell why requests are slow in production. This Skill produces the instrumentation file, entry-point wiring, metrics, logger, and a Docker Compose stack with Jaeger and Prometheus so you can see every slow query. ## Quick Start Ask the AI to add OpenTelemetry tracing, RED metrics, and trace-correlated logging to your Fastify and Prisma service, exporting to your preferred backend such as SigNoz, Grafana, Jaeger, or Datadog.

Frequently Asked Questions about opentelemetry-observability-architect

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add OpenTelemetry tracing to a Fastify app?

Create an instrumentation.ts file that starts the NodeSDK with auto-instrumentations, then import it as the very first line of your server entry point. Register the official @fastify/otel plugin so every route produces a trace span automatically.

How to trace BullMQ jobs with OpenTelemetry?

Inject the active trace context into the job data on the producer side using propagation.inject, then extract it in the worker with propagation.extract and start a child span. This links the job's span to the original request trace.

Why is my Fastify or Prisma code not being instrumented by OpenTelemetry?

The OTel SDK must be initialized before all other imports because it patches Node.js internals at import time. If Fastify or Prisma load first, those libraries are never instrumented, so import instrumentation.ts as line one of your entry point.

Does OpenTelemetry work with SigNoz, Grafana, and Datadog?

Yes, all three accept OTLP over HTTP. Set OTEL_EXPORTER_OTLP_ENDPOINT to the backend's OTLP URL and pass your ingestion token via the Authorization header; the same instrumentation code works across backends.

How do I correlate logs with traces in Node.js?

Use a Pino formatter that reads the active span via trace.getActiveSpan() and adds traceId and spanId to every log object. Each log line then links directly to its trace in Grafana or SigNoz.

Should health check endpoints be traced in OpenTelemetry?

No, health checks create noisy, low-value spans. Configure the HTTP instrumentation's ignoreIncomingRequestHook to skip URLs containing /health, and disable fs instrumentation which is similarly noisy.