Claude Code

The Claude Code integration collects OpenTelemetry log events and traces emitted by Anthropic Claude Code, the AI coding agent. It provides typed field mappings, ingest pipelines for structured queries, security-focused dashboards for tool invocation auditing, cost monitoring, and permission analysis, and a traces overview dashboard for LLM usage, latency, and tool activity.

Claude Code exports telemetry as OTLP (OpenTelemetry Protocol) logs and, optionally, traces. Each log event represents an action in an agentic session: tool calls (shell commands, file operations, MCP tool invocations), API requests, user prompts, permission decisions, and lifecycle events. Trace spans connect interactions, LLM requests, and tool calls into one trace per user turn. Trace export is in beta.

This integration requires Claude Code CLI version 2.1.0 or later, which supports OTLP log export. Traces require version 2.1.101 or later. Earlier versions emit beta trace spans but don't apply the verbosity gates to them, so spans can include prompts and tool content even when the gates are off.

Claude Code emits structured OTLP log records during agentic sessions. Each record carries an event name attribute identifying its type (mapped to event.action in ECS), along with event-specific attributes namespaced under claude_code.*. The Elastic Agent receives these events via its built-in OTLP HTTP receiver, applies an ingest pipeline that parses JSON-encoded tool parameters, extracts security-relevant fields, and categorizes events using ECS. The processed events are indexed into the logs-claude_code.events.otel-* data stream.

Trace spans are indexed into the traces-claude_code.otel-* data stream. Span attributes stay under attributes and use Elastic's native OTel mappings. The traces ingest pipeline adds ECS categorization based on span.type.

The integration processes these event types:

And these span types:

Claude Code also emits other span types (for example hook, and nested tool.blocked_on_user/tool.execution spans). These are indexed into the traces data stream but aren't ECS-categorized by the ingest pipeline.

• An Elastic deployment running version 9.4.0 or later.
• Claude Code CLI with telemetry enabled (CLAUDE_CODE_ENABLE_TELEMETRY=1).
• For traces: CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1.

Claude Code has four environment variables that control how much detail is included in log events and spans:

Enabling these gates provides richer forensic data but indexes potentially sensitive content (commands, file contents, prompts). When a gate is disabled, the corresponding fields are absent from the document — the pipeline handles this gracefully.

Organizations can enforce telemetry and verbosity gates fleet-wide via MDM profiles or the admin console. Managed settings cannot be overridden by user environment variables. This ensures telemetry cannot be silently redirected or disabled on managed devices.

For general instructions on installing integrations and deploying Elastic Agent, refer to the Getting started guide.

Prerequisites: Install this integration in Fleet before sending data. The installation creates the ingest pipelines, field mappings, and dashboards required for processing Claude Code events and spans.

Claude Code exports telemetry via OTLP. There are three deployment paths.

If your Elastic Cloud deployment supports managed OTLP ingestion, point Claude Code directly at the Elastic Cloud OTLP endpoint, no agent or collector infrastructure required. Configure the environment:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT="<your-elastic-cloud-otlp-endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey <your-api-key>"
export OTEL_RESOURCE_ATTRIBUTES="data_stream.dataset=claude_code.events.otel"

OTEL_RESOURCE_ATTRIBUTES applies to both logs and traces, so spans also arrive with the events dataset, in traces-claude_code.events.otel-*. Run the following in Kibana Dev Tools to reroute them to traces-claude_code.otel-*. The same pipeline handles Claude Code Desktop spans, which land in traces-generic.otel-* (see Claude Code Desktop traces).

PUT _ingest/pipeline/traces-claude-code-reroute
{
  "processors": [
    {
      "reroute": {
        "if": "['claude-code', 'claude-code-desktop'].contains(ctx.resource?.attributes?.get('service.name'))",
        "dataset": "claude_code.otel",
        "namespace": ["{{data_stream.namespace}}", "default"]
      }
    }
  ]
}
PUT _index_template/traces-claude-code-reroute
{
  "index_patterns": ["traces-claude_code.events.otel-*", "traces-generic.otel-*"],
  "priority": 150,
  "composed_of": ["traces@mappings", "traces@settings", "otel@mappings", "otel@settings", "traces-otel@mappings", "semconv-resource-to-ecs@mappings", "traces@custom", "traces-otel@custom", "ecs@mappings"],
  "ignore_missing_component_templates": ["traces@custom", "traces-otel@custom"],
  "template": {
    "settings": { "index.default_pipeline": "traces-claude-code-reroute" },
    "mappings": { "properties": { "data_stream.type": { "type": "constant_keyword", "value": "traces" } } }
  },
  "data_stream": { "hidden": false, "allow_custom_routing": false },
  "allow_auto_create": true
}

If either data stream already exists, roll it over so it picks up the new template, for example POST traces-generic.otel-default/_rollover. Run a rollover for each namespace you use.

The Elastic Agent exposes an OTLP HTTP receiver for each data stream on its configured HTTP endpoint (default port: 4318 for events, 4320 for traces). Configure Claude Code to send events and spans to the agent:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="http://<agent-host>:4318/v1/logs"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://<agent-host>:4320/v1/traces"
export OTEL_RESOURCE_ATTRIBUTES="data_stream.dataset=claude_code.events.otel"

Run the Elastic Distribution of the OpenTelemetry Collector as a gateway for your Claude Code clients. The collector sets the dataset for each signal, so Claude Code doesn't need OTEL_RESOURCE_ATTRIBUTES or auth headers. Configure Claude Code to send events and spans to the collector:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT="http://<collector-host>:4318"

Example collector configuration:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

connectors:
  elasticapm:

processors:
  elasticapm:
  transform/claude_code_logs:
    log_statements:
      - context: log
        statements:
          - set(attributes["data_stream.dataset"], "claude_code.events")
  transform/claude_code_traces:
    trace_statements:
      - context: span
        statements:
          - set(attributes["data_stream.dataset"], "claude_code")
      - context: spanevent
        statements:
          - set(attributes["data_stream.dataset"], "claude_code.events")

exporters:
  otlphttp/elasticsearch:
    endpoint: ${env:ELASTIC_ENDPOINT}/_otlp
    headers:
      Authorization: "ApiKey ${env:ELASTIC_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [transform/claude_code_logs]
      exporters: [otlphttp/elasticsearch]
    traces:
      receivers: [otlp]
      processors: [transform/claude_code_traces, elasticapm]
      exporters: [elasticapm, otlphttp/elasticsearch]
    metrics/aggregated-otel-metrics:
      receivers: [elasticapm]
      processors: []
      exporters: [otlphttp/elasticsearch]

Without the transform processors, data goes to logs-generic.otel-* and traces-generic.otel-*. Elasticsearch adds the .otel suffix to the dataset.

After deploying, run a short Claude Code session with telemetry enabled and confirm events appear in the logs-claude_code.events.otel-* data stream. For example, in Kibana Discover, filter on data_stream.dataset: claude_code.events.otel. For traces, filter on data_stream.dataset: claude_code.otel.

Claude Code Desktop ignores OTEL_RESOURCE_ATTRIBUTES (open issue) and reports resource.attributes.service.name: claude-code-desktop. When Desktop sends traces directly to Elasticsearch, its spans go to traces-generic.otel-*. Option B and Option C set the dataset for you. For Option A, the reroute pipeline in Option A moves Desktop spans to traces-claude_code.otel-* by service.name.

• Verify CLAUDE_CODE_ENABLE_TELEMETRY=1 is set in the environment where Claude Code runs.
• Check that the logs OTLP endpoint is reachable from the Claude Code host (curl -v http://<agent-host>:<port>/v1/logs, where <port> matches the HTTP Endpoint configured in the integration policy, default 4318).
• Confirm the Elastic Agent is running and the integration policy is assigned.

• Verify CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 and OTEL_TRACES_EXPORTER=otlp are set.
• Check that the traces endpoint is reachable (curl -v http://<agent-host>:<port>/v1/traces, default port 4320).
• For Option A, check traces-claude_code.events.otel-* and traces-generic.otel-*. If Claude Code spans are there, confirm the reroute pipeline and template from Option A are installed and that the data streams were rolled over.

Tool parameters, tool input, and prompt text are gated by environment variables (see Verbosity gates). If these fields are absent, enable the relevant gate. On managed devices, these may be controlled by organizational policy and cannot be overridden locally.

Events with event.kind: pipeline_error and a preserve_original_event tag indicate the events ingest pipeline encountered an error (typically malformed JSON in tool_parameters or tool_input). The original event is preserved for inspection. Spans with event.kind: pipeline_error indicate the traces ingest pipeline encountered an error. The failure details are in error.message.

Events — parses JSON-encoded tool parameters and inputs into structured fields for querying:

• tool_parameters (JSON string) → tool_parameters_flattened (flattened object)
• tool_input (JSON string) → tool_input_flattened (flattened object)

It also extracts:

• process.command_line from Bash tool full_command
• mcp_server_name and mcp_tool_name from MCP tool parameters
• file.path from file operation tool parameters
• url.full from web tool parameters

Traces — sets event.category and event.type from span.type, related.user from the user attributes, and extracts process.command_line and file.path from tool spans.

Tool invocation auditing — query all Bash commands executed by a user:

claude_code.tool_name: "Bash" AND event.action: "tool_result"

Permission decision analysis — find user_permanent auto-approvals (potential risk signal):

event.action: "tool_decision" AND claude_code.decision_source: "user_permanent"

Cost anomaly detection — aggregate cost_usd per user per day to detect unusual spending patterns.

MCP server access monitoring — track which MCP servers users connect to and which tools they invoke:

event.action: "mcp_server_connection" OR (event.action: "tool_result" AND claude_code.tool_name: "mcp_tool")

{
    "@timestamp": "2026-07-06T03:25:40.439Z",
    "claude_code": {
        "events": {
            "event": {
                "name": "user_prompt",
                "sequence": 0,
                "timestamp": "2026-07-06T03:25:40.439Z"
            },
            "has_hooks": true,
            "has_mcp": true,
            "prompt": {
                "id": "11111111-2222-3333-4444-555555555555"
            },
            "prompt_length": 18,
            "prompt_text": "What is 2 plus 2?",
            "session": {
                "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
            },
            "terminal": {
                "type": "xterm-256color"
            },
            "user": {
                "account_id": "user_01ExampleAccountId00000",
                "account_uuid": "00000000-1111-2222-3333-444444444444"
            }
        }
    },
    "data_stream": {
        "dataset": "claude_code.events.otel",
        "namespace": "55955",
        "type": "logs"
    },
    "ecs": {
        "version": "9.3.0"
    },
    "event": {
        "action": "user_prompt",
        "agent_id_status": "missing",
        "dataset": "claude_code.events.otel",
        "ingested": "2026-07-06T03:25:50Z",
        "kind": "event",
        "original": "{\"observed_timestamp\":\"1783308340439.840708\",\"@timestamp\":\"1783308340439.834018\",\"resource\":{\"attributes\":{\"service.name\":\"claude-code\",\"service.version\":\"2.1.175\",\"host.arch\":\"amd64\",\"os.type\":\"linux\",\"os.version\":\"6.17.0-14-generic\"}},\"data_stream\":{\"namespace\":\"55955\",\"type\":\"logs\",\"dataset\":\"claude_code.events.otel\"},\"scope\":{\"name\":\"com.anthropic.claude_code.events\",\"version\":\"2.1.175\"},\"event_name\":\"user_prompt\",\"attributes\":{\"user.id\":\"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\",\"user.account_uuid\":\"00000000-1111-2222-3333-444444444444\",\"terminal.type\":\"xterm-256color\",\"event.name\":\"user_prompt\",\"event.timestamp\":\"2026-07-06T03:25:40.439819114Z\",\"prompt.id\":\"11111111-2222-3333-4444-555555555555\",\"event.sequence\":0,\"user.email\":\"test@example.com\",\"prompt_length\":18,\"elastic.preserve_original_event\":\"true\",\"organization.id\":\"00000000-0000-0000-0000-000000000001\",\"has_mcp\":\"true\",\"user.account_id\":\"user_01ExampleAccountId00000\",\"prompt\":\"What is 2 plus 2?\",\"session.id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"has_hooks\":\"true\"},\"body\":{\"text\":\"claude_code.user_prompt\"},\"event\":{},\"_version_type\":\"internal\",\"_index\":\"logs-claude_code.events.otel-55955\",\"_id\":null,\"_version\":-4}",
        "outcome": "unknown",
        "provider": "claude-code"
    },
    "gen_ai": {
        "provider": {
            "name": "anthropic"
        }
    },
    "host": {
        "arch": "amd64",
        "architecture": "amd64",
        "os": {
            "platform": "linux",
            "version": "6.17.0-14-generic"
        }
    },
    "observed_timestamp": "2026-07-06T03:25:40.439840708Z",
    "organization": {
        "id": "00000000-0000-0000-0000-000000000001"
    },
    "os": {
        "type": "linux",
        "version": "6.17.0-14-generic"
    },
    "related": {
        "user": [
            "test@example.com",
            "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
        ]
    },
    "resource": {
        "attributes": {
            "host": {
                "arch": "amd64"
            },
            "os": {
                "type": "linux",
                "version": "6.17.0-14-generic"
            },
            "service": {
                "name": "claude-code",
                "version": "2.1.175"
            }
        }
    },
    "scope": {
        "name": "com.anthropic.claude_code.events",
        "version": "2.1.175"
    },
    "service": {
        "name": "claude-code",
        "version": "2.1.175"
    },
    "tags": "preserve_original_event",
    "user": {
        "email": "test@example.com",
        "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
    }
}

{
    "@timestamp": "2026-10-07T17:19:12.905Z",
    "attributes": {
        "interaction": {
            "duration_ms": 12545,
            "sequence": 1
        },
        "organization": {
            "id": "00000000-0000-0000-0000-000000000001"
        },
        "parent": {
            "source": "none"
        },
        "queued_sends": 0,
        "session": {
            "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
        },
        "span": {
            "type": "interaction"
        },
        "terminal": {
            "type": "xterm-256color"
        },
        "user": {
            "account_id": "user_01ExampleAccountId00000",
            "account_uuid": "00000000-1111-2222-3333-444444444444",
            "email": "test@example.com",
            "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
        },
        "user_prompt_length": 17
    },
    "data_stream": {
        "dataset": "claude_code.otel",
        "namespace": "44902",
        "type": "traces"
    },
    "duration": 12545000000,
    "ecs": {
        "version": "9.3.0"
    },
    "event": {
        "agent_id_status": "missing",
        "category": [
            "session"
        ],
        "dataset": "claude_code.otel",
        "ingested": "2026-10-07T17:19:35Z",
        "kind": "event",
        "type": [
            "info"
        ]
    },
    "host": {
        "arch": "amd64",
        "architecture": "amd64",
        "os": {
            "platform": "linux",
            "version": "6.17.0-14-generic"
        }
    },
    "interaction": {
        "duration_ms": 12545,
        "sequence": 1
    },
    "kind": "Internal",
    "name": "claude_code.interaction",
    "organization": {
        "id": "00000000-0000-0000-0000-000000000001"
    },
    "os": {
        "type": "linux",
        "version": "6.17.0-14-generic"
    },
    "parent": {
        "source": "none"
    },
    "queued_sends": 0,
    "related": {
        "user": [
            "test@example.com",
            "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
        ]
    },
    "resource": {
        "attributes": {
            "host": {
                "arch": "amd64"
            },
            "os": {
                "type": "linux",
                "version": "6.17.0-14-generic"
            },
            "service": {
                "name": "claude-code",
                "version": "2.1.175"
            }
        }
    },
    "scope": {
        "name": "com.anthropic.claude_code.tracing",
        "version": "1.0.0"
    },
    "service": {
        "name": "claude-code",
        "version": "2.1.175"
    },
    "session": {
        "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    },
    "span": {
        "id": "4a33403362f74185",
        "name": "claude_code.interaction",
        "type": "interaction"
    },
    "span_id": "4a33403362f74185",
    "terminal": {
        "type": "xterm-256color"
    },
    "trace": {
        "id": "84487adcee70a28b25f95b793b93b3fc"
    },
    "trace_id": "84487adcee70a28b25f95b793b93b3fc",
    "user": {
        "account_id": "user_01ExampleAccountId00000",
        "account_uuid": "00000000-1111-2222-3333-444444444444",
        "email": "test@example.com",
        "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
    },
    "user_prompt_length": 17
}

This integration includes one or more Kibana dashboards that visualizes the data collected by the integration. The screenshots below illustrate how the ingested data is displayed.