opentelemetry-observability-architect

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @opentelemetry/sdk-node, @opentelemetry/api, @opentelemetry/resources, @opentelemetry/semantic-conventions, @opentelemetry/auto-instrumentations-node, @opentelemetry/exporter-trace-otlp-http, @opentelemetry/exporter-metrics-otlp-http, @opentelemetry/sdk-metrics, @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 sets up a complete OpenTelemetry pipeline so every request, database query, queue job, and log line is correlated and visible in your observability backend. ## Core Features & Use Cases - Auto-instrumentation setup: Generates instrumentation.ts with the OTel NodeSDK, auto-instrumentations for Fastify, HTTP, and Prisma, loaded before all other imports so nothing is missed. - Custom spans and queue tracing: Adds business-logic spans and propagates trace context from BullMQ producers to workers so async jobs stay connected to their originating request. - RED metrics and correlated logs: Configures rate/error/duration histograms per route and a Pino logger that injects traceId and spanId into every log line. - Use Case: You notice intermittent slow API responses in production. After running this Skill, you open SigNoz, find the slow trace, and see exactly which Prisma query or BullMQ job caused the delay. ## Quick Start Ask the AI to add OpenTelemetry tracing, RED metrics, and structured 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 initializes the OTel NodeSDK with auto-instrumentations, then import it as the very first line of your server entry point. Register the official @fastify/otel plugin to create spans for every route automatically.

How do I 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 new span under that parent context. This keeps queue jobs connected to the originating request trace.

Why is my OpenTelemetry instrumentation not capturing Fastify or Prisma spans?

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 not instrumented, so ensure instrumentation.ts is imported on line 1 of your entry point.

Can OpenTelemetry export to SigNoz, Grafana, or Datadog?

Yes, the OTLP HTTP exporter works with any OTLP-compatible backend by changing the OTEL_EXPORTER_OTLP_ENDPOINT and auth token environment variables. The same instrumentation code works unchanged across SigNoz, Grafana Cloud, Datadog, and local Jaeger.

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

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

Should I trace health check endpoints in production?

No, health check routes generate high-volume, low-value spans that add noise and cost. Configure the HTTP instrumentation's ignoreIncomingRequestHook to skip URLs like /health while keeping all other routes traced.