Custom Telemetry Enhanced

Advanced telemetry configuration setting for routing Claude Code metrics to custom OTEL-compatible endpoints with fine-grained control.

When to Use This Setting

Apply this setting when you need to:

• Route Claude Code telemetry data to your own OpenTelemetry-compatible metrics collection endpoint
• Disable default telemetry while enabling custom metrics export for internal observability platforms
• Configure granular control over which telemetry signals (metrics, traces, logs) are collected and where they are sent Consider alternatives when:
• You want to completely disable all telemetry without routing data anywhere
• The default Claude Code telemetry collection meets your observability needs without customization

Quick Start

Configuration

Copy
name: custom-telemetry-enhanced
type: setting
category: telemetry

Example Application

Copy
claude setting:apply custom-telemetry-enhanced

Example Output

Setting applied. Changes:
- CLAUDE_CODE_ENABLE_TELEMETRY: 0
- OTEL_METRICS_EXPORTER: custom
- telemetry_mode: custom endpoint routing
- default_collection: disabled

Core Concepts

Custom Telemetry Overview

Aspect	Details
Default Telemetry	Disabled by setting CLAUDE_CODE_ENABLE_TELEMETRY to 0
Metrics Exporter	Set to custom mode for routing to your own OTEL-compatible backend
Configuration Method	Uses environment variables injected into the Claude Code runtime
Signal Types	Supports metrics, traces, and logs depending on your OTEL collector setup
Backend Compatibility	Works with Prometheus, Grafana, Datadog, New Relic, and any OTEL-compatible platform

Telemetry Routing Architecture

+-------------------+     +---------------------+     +------------------+
| Claude Code       |---->| OTEL SDK            |---->| Custom Exporter  |
| runtime metrics   |     | metrics pipeline    |     | your endpoint    |
| traces, logs      |     | configured via env  |     | OTEL protocol    |
+-------------------+     +---------------------+     +------------------+
                                   |                          |
                                   v                          v
                          +---------------------+    +------------------+
                          | Default Telemetry   |    | Your Observability|
                          | DISABLED (flag = 0) |    | Prometheus/Grafana|
                          +---------------------+    | Datadog/NewRelic  |
                                                     +------------------+

Configuration

Parameter	Type	Default	Description
CLAUDE_CODE_ENABLE_TELEMETRY	string	"0"	Disables default Claude Code telemetry collection
OTEL_METRICS_EXPORTER	string	"custom"	Sets the OpenTelemetry metrics exporter to custom mode
OTEL_EXPORTER_OTLP_ENDPOINT	string	""	URL of your OTEL collector endpoint for receiving telemetry
OTEL_EXPORTER_OTLP_HEADERS	string	""	Authentication headers for your OTEL collector endpoint
OTEL_SERVICE_NAME	string	"claude-code"	Service name tag applied to all exported telemetry data

Best Practices

1. Set up your OTEL collector first - Before applying this setting, ensure your OpenTelemetry collector or compatible backend is running and accessible. Without a functioning endpoint, the custom exporter will silently drop metrics.
2. Test with a local collector - Start with a local OTEL collector running on localhost:4317 to verify the telemetry pipeline works before routing to your production observability platform. This prevents noise in production dashboards during testing.
3. Add authentication headers - If your OTEL endpoint requires authentication, set OTEL_EXPORTER_OTLP_HEADERS with your API key or bearer token. Format as comma-separated key-value pairs for multiple headers.
4. Use service name for filtering - Set OTEL_SERVICE_NAME to something descriptive like "claude-code-dev" or "claude-code-ci" so you can filter telemetry data by context in your observability dashboard.
5. Monitor exporter health - Custom exporters can fail silently. Set up health checks or dead-letter queues in your OTEL collector to detect when telemetry data stops flowing from your Claude Code instances.

Common Issues

1. No data appears in your observability platform - The OTEL_EXPORTER_OTLP_ENDPOINT may be incorrect or unreachable. Verify the endpoint URL and ensure network connectivity from your development machine to the collector.
2. Authentication errors in exporter logs - The OTEL_EXPORTER_OTLP_HEADERS may be malformed. Ensure headers use the correct format and that your API key is valid and has not expired.
3. Telemetry still appears to be sent to default endpoint - Both CLAUDE_CODE_ENABLE_TELEMETRY=0 and the custom exporter configuration must be applied. Verify both environment variables are set in the same shell session where Claude Code runs.