Instrument Node.js with OpenTelemetry: A Skill That Gets It Right

Where this fits

You're debugging a Node.js microservice that's failing in production, but you have zero traces. You need to add OpenTelemetry quickly—without spelunking through SDK docs or fighting ESM/CJS import order. The otel-js skill gives your agent the exact references to configure NodeSDK via declarative YAML, set up auto-instrumentations, and migrate from v1 to v2—so you can get observability running before your next deploy.

Why agents benefit

• Declarative YAML first: The skill references OTEL_CONFIG_FILE and @opentelemetry/configuration, so agents can generate a single YAML config instead of writing verbose SDK setup code.
• ESM vs CJS clarity: It provides import-order patterns that avoid the classic "module not found" or "instrumentation not applied" pitfalls—agents can pick the right pattern for your project's module system.
• Version-aware guidance: It points to npm view @opentelemetry/configuration version and v2.0 migration notes, so agents don't suggest outdated APIs.
• Self-contained references: Each reference file is standalone, letting agents load only what's needed for the task (setup, review, or migration) without irrelevant noise.
• Trigger-based routing: The skill activates on natural phrases like "setup otel in node" or "node tracing setup," ensuring your agent knows exactly when to apply it.

Practical scenarios

Adding OTel to a new Express service

Your agent reads a service's package.json, sees it's CJS, and uses the skill to generate a otel-config.yaml plus a tracing.js entry point that imports @opentelemetry/sdk-node in the correct order—no more guessing.

Reviewing an existing OTel setup for v2 migration

You suspect your traces are incomplete because you're on an old SDK. The skill's migration reference helps your agent identify deprecated APIs and propose a declarative YAML approach, reducing boilerplate and aligning with the v2 standard.

Debugging missing spans in a TypeScript monorepo

Your agent uses the skill to check auto-instrumentation coverage for HTTP, gRPC, and database clients. It spots that @opentelemetry/instrumentation-express isn't loaded and suggests the right import in your ESM build—fixing the gap without a full rewrite.

Add it to your agent workflow

Install the skill with:

npx skills add ollygarden/opentelemetry-agent-skills --skill otel-js

Then, in your agent's prompt, simply say: "Set up OpenTelemetry in my Node.js service using declarative YAML." The skill will load the relevant reference and guide the agent through configuration, including import order and SDK initialization. You can also ask it to review an existing setup against the latest @opentelemetry/configuration version.

Compare before adopting

Before you commit, compare otel-js against alternatives by checking:

• Quality signals: Does the README link to upstream sources? Are references updated with SDK releases? (This skill explicitly lists npm view commands.)
• Maintenance freshness: Check the last commit and issue activity on the GitHub repo—stale skills can mislead agents.
• Alternatives: Look for other OTel skills that cover different runtimes (Python, Go) or more specialized instrumentation—you might need a broader suite.
• Workflow fit: Does the skill match your module system (ESM vs CJS) and your config style (YAML vs code)? The declarative approach is a strong default but not universal.

Why it is worth tracking

With 97 stars and a clear, focused scope, otel-js shows community momentum—developers are actively using it. Its design of self-contained references and version-aware guidance makes it a reliable, low-friction addition to any agent working with Node.js observability. Re-evaluate it when OpenTelemetry NodeSDK v2.0 stabilizes or if you adopt a configuration-as-code pattern that diverges from the YAML-first approach. For a one-stop overview, see the skill listing on OpenAgentSkill.