otel-ottl

Guides an AI coding agent in writing and debugging OpenTelemetry Transformation Language expressions for supported Collector components. These expressions can filter unwanted monitoring data, redact sensitive values, reshape attributes and add context.

WHEN TO USE

SCOPE

USE FOR

Drop noisy or low-value spans, metrics, or logs before they leave the Collector.
Redact sensitive fields, like passwords or card numbers, out of telemetry in flight.
Rewrite high-cardinality values, like user IDs or full URLs, into safe, bounded ones.
Add extra static attributes to telemetry as it passes through the Collector.
Work out why a transform or filter processor isn't behaving the way you expect.
Backfill missing timestamps or fix malformed fields before data reaches your backend.

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 (8)

OpenTelemetry Transformation Language (OTTL)

Components that use OTTL

OTTL is not limited to the transform and filter processors. Processors (transform, filter, attributes, span, tailsampling, cumulativetodelta, logdedup, lookup), connectors (routing, count, sum, signaltometrics), and the hostmetrics receiver all accept OTTL expressions. See components for the full list with use cases.

OTTL syntax

Path expressions

Navigate telemetry data using dot notation:

span.name
span.attributes["http.method"]
resource.attributes["service.name"]

Contexts (first path segment): resource, scope, span, spanevent, metric, datapoint, log.

Enumerations

Use int64 constants for enumeration fields:

span.status.code == STATUS_CODE_ERROR
span.kind == SPAN_KIND_SERVER

Operators

Assignment: = — Comparison: ==, !=, >, <, >=, <= — Logical: and, or, not

Functions

Converters (uppercase, return values):

ToUpperCase(span.attributes["http.request.method"])
Substring(log.body.string, 0, 1024)
Concat(["prefix", span.attributes["request.id"]], "-")
IsMatch(metric.name, "^k8s\\..*$")

Editors (lowercase, modify data in-place):

set(span.attributes["region"], "us-east-1")
delete_key(resource.attributes, "internal.key")
limit(log.attributes, 10, [])

See function-reference for the full list of editors and converters.

Conditional statements

Use where to apply transformations conditionally:

span.attributes["db.statement"] = "REDACTED" where resource.attributes["service.name"] == "accounting"

Nil checks

Use nil for absence checking (not null):

resource.attributes["service.name"] != nil

Validation workflow

Validate config syntax — run otelcol validate --config=config.yaml to catch compilation errors before starting the Collector.
Test with the debug exporter — route transformed telemetry to a debug exporter and inspect the output:

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform]
      exporters: [debug]   # swap in production exporter once validated

Set error_mode: ignore in production — see Error handling.
Promote to production exporters — replace debug with the production exporter.

Common patterns

Set attributes
Drop telemetry by pattern
Drop stale data
Backfill missing timestamps
Filter processor example
Transform processor example
Defensive nil checks
Redact sensitive data — strategies: replace, mask, hash, delete, and drop.
Normalize high-cardinality attributes — path segments, IP masking, and attribute count/length limits.
Enrich telemetry with static attributes

Error handling

Compilation errors

Occur during processor initialization and prevent Collector startup:

Invalid syntax (missing quotes)
Unknown functions
Invalid path expressions
Type mismatches

Runtime errors

Occur during telemetry processing:

Accessing non-existent attributes
Type conversion failures
Function execution errors

Error mode configuration

Set error_mode explicitly for clarity; ignore is the default.

Mode	Behavior	When to use
`ignore` (default)	Logs the error and continues to the next statement	Production and general use — the default for the transform and filter processors
`propagate`	Returns the error up the pipeline, dropping the payload from the Collector	Development and strict environments where you want to catch every error
`silent`	Ignores errors without logging	High-volume pipelines with known-safe transforms where error logs are noise

processors:
  transform:
    error_mode: ignore
    trace_statements:
      - set(span.attributes["parsed"], ParseJSON(span.attributes["json_body"]))

Statements are a flat list; the Collector infers the context (span, metric, datapoint, log, and so on) from the path prefixes. Use the object form with an explicit context: only when a statement group mixes paths that cannot be inferred to a single context, or when you need a group-level condition or error_mode.

Performance

Use where clauses to skip items early.

# BAD — runs replace_pattern on every span
replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}")

# GOOD — skips spans that lack the attribute
replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}") where span.attributes["url.path"] != nil

References

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-ottl" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

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 Transformation Language (OTTL)

Components that use OTTL

OTTL syntax

Path expressions

Enumerations

Operators

Functions

Conditional statements

Nil checks

Validation workflow

Common patterns

Error handling

Compilation errors

Runtime errors

Error mode configuration

Performance

References

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-instrumentation

otel-semantic-conventions

MCP keyword matches

Sentry MCP

VictoriaMetrics MCP Server

Perplexity Comet Bridge

PostgreSQL-Ops MCP