otel-instrumentation

Guides an AI coding agent in adding traces, metrics and logs to backend and browser applications with OpenTelemetry. It covers language-specific setup, connecting related signals, protecting sensitive data and checking the resulting monitoring data.

WHEN TO USE

SCOPE

USE FOR

Add tracing, metrics, and logging to a service in Node.js, Python, Go, Java, Scala, .NET, Ruby, or PHP, or to a browser or Next.js app.
Decide what a span, metric, or log line should be named and what it should record.
Scrub personal or sensitive data out of your telemetry before it leaves the service.
Confirm new instrumentation is actually reaching your monitoring backend after a deploy.
Record the values passed into a slow or failing database query, in Java, Scala, .NET, Python, Node.js, or Go. The skill notes that no OpenTelemetry SDK captures them by default because they often carry sensitive data, and it advises turning capture on, in most cases, only outside production.
Instrument a Next.js app end to end, on both the server and the browser.

NOT FOR

Deciding sampling rates or policies — that belongs in the Collector, not the SDK.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (5)

OpenTelemetry Instrumentation Guide

Expert guidance for implementing high-quality, cost-efficient OpenTelemetry telemetry.

Rules & Quick Reference

Use Case / Rule	Description
telemetry	Entrypoint — signal types, correlation, and navigation
resolve-values	Resolving configuration values from the codebase
verify-dependencies	Verifying instrumentation packages and versions exist before adding them
resources	Resource attributes — service identity and environment
k8s	Kubernetes deployment — downward API, pod spec
spans	Spans — naming, kind, status, and hygiene
logs	Logs — structured logging, severity, trace correlation
metrics	Metrics — instrument types, naming, units, cardinality
sensitive-data	Sensitive data — PII prevention, sanitization, redaction
capture-database-query-parameters	Prepared-statement parameter capture per language (Java, .NET, Python, Node.js, Go)
validation	Telemetry validation — post-deployment verification checklist
nodejs	Node.js instrumentation setup
go	Go instrumentation setup
python	Python instrumentation setup
java	Java instrumentation setup
scala	Scala instrumentation setup
dotnet	.NET instrumentation setup
ruby	Ruby instrumentation setup
php	PHP instrumentation setup
browser	Browser instrumentation setup
nextjs	Next.js full-stack instrumentation (App Router)

Official documentation

Getting started

Follow these steps when instrumenting an application from scratch:

Pick your SDK rule — choose the language-specific rule from the table above (e.g., nodejs, python).
Set up resource attributes — define service identity and environment per resources.
Add spans, metrics, and logs — instrument your code following spans, metrics, and logs.
Guard sensitive data — scrub PII before export per sensitive-data.
Validate — confirm telemetry reaches the backend using the checklist in validation.

The snippet below shows a complete span with attributes and status for Node.js — see nodejs for full setup including SDK initialisation, exporter configuration, and auto-instrumentation:

import { trace, SpanStatusCode } from '@opentelemetry/api';
const tracer = trace.getTracer('my-service', '1.0.0');

tracer.startActiveSpan('operation-name', async (span) => {
  try {
    span.setAttribute('user.id', userId);
    span.setAttribute('order.id', orderId);

    const result = await processOrder(orderId);

    span.setAttribute('order.status', result.status);
    span.setStatus({ code: SpanStatusCode.OK });
    return result;
  } catch (err) {
    // Record the exception as a structured log record, not span.recordException — see rules/spans.md
    span.setStatus({ code: SpanStatusCode.ERROR, message: `${err.name}: ${err.message}` });
    const spanContext = span.spanContext();
    logger.error('operation-name.failed', {
      'trace_id': spanContext.traceId,
      'span_id': spanContext.spanId,
      'exception.type': err.name,
      'exception.message': err.message,
      'exception.stacktrace': err.stack,
    });
    throw err;
  } finally {
    span.end();
  }
});

Key principles

Signal density over volume

Every telemetry item should serve one of three purposes:

Detect - Help identify that something is wrong
Localize - Help pinpoint where the problem is
Explain - Help understand why it happened

If it doesn't serve one of these purposes, don't emit it.

Sample in the pipeline, not the SDK

Use the AlwaysOn sampler (the default) in every SDK. Do not configure SDK-side samplers — they make irreversible decisions before the outcome of a request is known. Defer all sampling to the Collector, where policies can be changed centrally without redeploying applications.

SDK (AlwaysOn)  →  Collector (sampling)  →  Backend (retention)
     ↓                    ↓                       ↓
  All spans         Head or tail            Storage policies
  exported          sampling applied

This skill ships inside the Dash0 Agent Skills plugin.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add dash0hq/agent-skills --skill otel-instrumentation otel-collector --full-depth

It installs two skills: this one and otel-collector, which it relies on. Once these skills are installed where Claude Code loads them, their descriptions help Claude decide when to use them.

Install the whole plugin

This route installs the Dash0 Agent Skills plugin package selected for your AI tool.

Add the marketplace, then install the plugin

Enter both lines in a Claude Code session. They add Dash0’s marketplace and open the four-skill plugin for installation; choose where to enable it in the install panel.

Install checklist

Have Claude Code available to enter these session commands.
Choose dash0-agent-skills; Dash0’s marketplace also lists a different plugin named dash0-agent-plugin.

/plugin marketplace add dash0hq/claude-marketplace

/plugin install dash0-agent-skills@dash0

Installation and loading

Choose user, project or local scope according to where you want the plugin enabled.
Read the install summary and follow any reload instruction. Check the / menu for the plugin’s skills.
Your agent can select relevant skills automatically. To choose one explicitly, use /plugin-name:skill-name for plugin skills; direct skill installations use /skill-name.

Clone Dash0’s repository

Run this terminal command to copy Dash0’s four-skill repository into ~/.agents/skills/dash0-agent-skills.

Install checklist

Have Git installed to clone the repository.
If the destination already contains this repository, reuse it rather than cloning into the same folder again.

git clone https://github.com/dash0hq/agent-skills.git ~/.agents/skills/dash0-agent-skills

Installation and loading

Open /skills and check for the four skill names. Your agent can select a matching skill automatically; use /skills or $ to choose explicitly.
In a Vercel Sandbox, Codex CLI 0.162.1 listed all four skills through codex debug prompt-input without login; removing this clone removed them from the list.

Install from Dash0’s GitHub repository

Enter Dash0’s command in an interactive GitHub Copilot CLI session. It requests a direct plugin installation from the repository; GitHub documents direct installations under ~/.copilot/installed-plugins/_direct/.

Install checklist

Use GitHub Copilot CLI for this session command; other Copilot interfaces have their own installation controls.
Copilot CLI 1.0.95 warns that direct repository installs are deprecated; a future release will accept only plugin@marketplace installs.

/plugin install https://github.com/dash0hq/agent-skills

Installation and loading

Use copilot skill list to check for the four skills. Your agent can load relevant skills automatically.
In a Vercel Sandbox with no Dash0 clones active, Copilot CLI 1.0.95 installed and listed four skills without login through terminal subcommands; session slash commands were untested.

Clone into your local skills folder

Dash0 documents this terminal command to copy its four-skill repository into ~/.cursor/skills/dash0-agent-skills. Cursor lists ~/.cursor/skills as a local user skills location.

Install checklist

Have Git installed to clone the repository.
This folder stays on your machine. For Cloud Agents, sync personal Cursor skills or use project skills.
Discovery of the four nested skills through this clone route has not been tested in Cursor.

git clone https://github.com/dash0hq/agent-skills.git  ~/.cursor/skills/dash0-agent-skills

Installation and loading

In Agent chat, type / and check for the four skill names before relying on them.
Your agent selects relevant skills from context. Selecting a skill through / attaches it to that message.

Install the Gemini CLI extension

Run this command in a terminal. It installs Dash0’s repository as a Gemini CLI extension containing four skills under ~/.gemini/extensions/dash0-agent-skills.

Install checklist

Have Gemini CLI available to run the extension installer.
Have Git installed; Gemini CLI requires it for extensions installed from GitHub.
In our Vercel Sandbox run, Gemini CLI 0.63.0 prompted for workspace trust and skill approval in an initially untrusted workspace; review installation prompts.

gemini extensions install https://github.com/dash0hq/agent-skills

Installation and loading

Restart your Gemini CLI session for the extension changes to take effect.
Use /skills list to inspect discovered skills. When your agent proposes activation for a matching task, review its skill-directory access prompt before approving.

Clone into the local skills folder

Run this terminal command to copy Dash0’s four-skill repository into ~/.openclaw/skills/dash0-agent-skills.

Install checklist

Have Git installed to clone the repository.
Check your OpenClaw state directory; the command targets ~/.openclaw, while managed skills follow the configured state directory.

git clone https://github.com/dash0hq/agent-skills.git ~/.openclaw/skills/dash0-agent-skills

Installation and loading

In the Control UI, type $ and check for the four skills. Your agent can select them automatically; use $skill-name to reference one explicitly.
In a Vercel Sandbox, OpenClaw 2026.6.35 listed four skills through openclaw skills list --json with only this OpenClaw clone active; invocation was untested.

Clone Dash0’s repository

Run this terminal command to copy Dash0’s four-skill repository into ~/.agents/skills/dash0-agent-skills.

Install checklist

Have Git installed to clone the repository.
If you already cloned this repository for Codex, reuse it: both panels target the same directory.

git clone https://github.com/dash0hq/agent-skills.git ~/.agents/skills/dash0-agent-skills

Installation and loading

Your agent can select and load these skills when relevant. Their metadata does not enable /name commands in OpenCode.
In a Vercel Sandbox, OpenCode 1.19.0 listed four skills through opencode debug skill without login; removing this clone removed them from the list. Invocation was untested.

Install into your repository

Run this command in a terminal inside your Git repository. It installs Dash0’s four-skill registry plugin under .tessl/plugins/dash0/agent-skills and links skills into detected agents’ directories.

Install checklist

Install Tessl CLI first; native, Homebrew and winget installers are available. npm installation is deprecated.
In our Vercel Sandbox run, Tessl CLI 0.114.0 initialized an empty Git repository without tessl.json, wrote AGENTS.md and configured four detected agents’ Tessl MCP connections.
Review these project and agent configuration changes before installing.

tessl install dash0/agent-skills

Installation and loading

Tessl records the plugin reference in tessl.json.
Tessl says your agent loads relevant skills from your task, files and conversation context, without explicit invocation. Loading through these links was not tested.

Good to know

Tessl’s --global option installs plugins under ~/.tessl/plugins/ for use across repositories.
That sandbox installation completed without login.

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub

OpenTelemetry Instrumentation Guide

Rules & Quick Reference

Official documentation

Getting started

Key principles

Signal density over volume

Sample in the pipeline, not the SDK

Local tool required

Install just this skill

Install the whole plugin

Add the marketplace, then install the plugin

Clone Dash0’s repository

Install from Dash0’s GitHub repository

Clone into your local skills folder

Install the Gemini CLI extension

Clone into the local skills folder

Clone Dash0’s repository

Install into your repository

What's inside

More skills

otel-collector

otel-ottl

otel-semantic-conventions

MCP keyword matches

Sentry MCP

VictoriaMetrics MCP Server

Perplexity Comet Bridge

PostgreSQL-Ops MCP