Claude Code Control and Observability with OpenTelemetry

Claude Code observability is the evidence layer for a secure coding-agent rollout. Permissions, hooks, managed MCP, sandboxing, dev containers, and CI/CD gates decide what the agent may do. OpenTelemetry shows what the agent actually asked to do, which policy decided the action, which tools ran, which MCP servers connected, which hooks executed, and where failures occurred.

Anthropic documents Claude Code telemetry in the Monitoring usage guide and exposes related observability paths for the Agent SDK. The same rollout should also account for Anthropic's Security, Settings, Permissions, Hooks, and Managed MCP documentation. The OpenTelemetry side should follow the OTLP exporter configuration model and normal OpenTelemetry signal concepts for metrics, logs, and traces.

The control point is simple. Claude Code should emit enough telemetry for a security team to reconstruct a coding-agent action from prompt to tool call to policy decision to execution result. That evidence should reach a backend where alerts, dashboards, incident response, compliance review, and regression tests can use it.

Search Intent This Guide Covers

People searching for Claude Code control and observability usually want a practical deployment answer. The common searches include Claude Code OpenTelemetry, Claude Code observability, Claude Code monitoring, Claude Code SIEM, Claude Code audit events, Claude Code tool decision events, Claude Code MCP observability, Claude Code hooks observability, Claude Code Agent SDK observability, and Claude Code distributed tracing.

Those searches point to one operating model. Claude Code needs runtime controls and evidence together. Permissions without telemetry leave security teams guessing after an incident. Telemetry without controls creates a record of what happened without preventing the next failure. A mature deployment connects both.

The direct answer is this. Claude Code control and observability require managed OpenTelemetry export, privacy-aware event configuration, tool-decision tracking, MCP and hook events, permission-mode alerts, trace correlation for Agent SDK and non-interactive jobs, SIEM routing, and retests that turn incidents into durable checks.

What OpenTelemetry Gives You

OpenTelemetry gives Claude Code three signal types. Metrics describe aggregate activity over time. Events travel through the logs/events path and describe discrete actions. Traces connect a user prompt to the model calls, tool calls, hook execution, and permission waits that happen underneath.

Metrics answer fleet-level questions. How many sessions started? Which models cost the most? Which teams use the most tokens? How many pull requests did Claude Code create?

Events answer security questions. Which command ran? Was the tool call allowed or denied? Did the decision come from config, a hook, or the user? Which MCP server connected? Which hook blocked the action?

Traces answer causality questions. Which user prompt triggered this model request? Which tool calls followed? How long did the session wait for permission? Did a subagent run the tool? Did a script inherit trace context from Claude Code?

Control And Observability Architecture

A secure architecture has four control planes.

Claude Code observability should be deployed through managed settings for enterprise use. User-level environment variables are useful for testing. Managed settings are the right place for the organization baseline because users cannot casually override them.

The backend should usually be an OpenTelemetry Collector first. The collector can receive OTLP, apply redaction or routing, attach environment metadata, and forward to a SIEM, log analytics system, metrics backend, or trace backend. Direct export from every developer machine to a production SIEM can work, but a collector gives security teams a better place to manage credentials, sampling, filtering, and schema changes.

Quick Start For Local Validation

Start with console or local OTLP before configuring the enterprise path. The goal is to prove that Claude Code emits the expected signals and that your backend can parse them.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000

claude

For production, restore normal export intervals and move the configuration into managed settings. Anthropic's docs state that metrics default to a longer interval than logs, which is usually appropriate for production. Short intervals are useful while proving the pipeline.

Use a local test session that runs a safe command, rejects a risky command, connects to an approved MCP server if your environment uses MCP, and triggers a hook. Confirm that every event appears with the expected user, session, repository, tool, and decision fields.

Managed Settings For Observability

Use managed settings to enforce telemetry consistently across the organization.

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel-collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Managed telemetry configuration should include owners. Security operations owns SIEM ingestion and alerts. Developer platform owns distribution to workstations and dev containers. Privacy and legal review content-bearing fields. AppSec owns the detection logic that maps tool activity to code risk.

Claude Code does not pass OTEL_* exporter variables into subprocesses such as Bash, hooks, MCP servers, and language servers. That separation is useful because child tools do not automatically inherit SIEM credentials. If a subprocess needs its own telemetry, set its exporter variables directly in that subprocess or wrapper.

What To Log By Default

The safest default is metadata-first logging. Enable metrics and logs. Keep prompt content, raw API bodies, full tool content, and broad tool argument logging disabled until the privacy review is complete.

For security operations, OTEL_LOG_TOOL_DETAILS=1 is the most important content-adjacent switch. It gives visibility into Bash commands, MCP server and tool names, skill names, and tool input arguments. That data can contain sensitive values, so it belongs behind a redaction and retention decision.

The strongest enterprise pattern enables tool details for high-risk repositories, routes the events through a collector, redacts known secret patterns, and forwards normalized fields to the SIEM. Raw bodies and full tool content should be reserved for tightly controlled investigations or regulated audit pipelines.

Security Events To Monitor

Claude Code emits many event types. Security teams should start with a smaller detection set that maps directly to risk.

The best SIEM rules are specific. Alert on a move from plan or default to bypassPermissions. Alert on an unapproved MCP server connection. Alert when a hook that protects production files fails. Alert on a Bash command that includes upload tools, deployment tools, package publishing, database migration, or infrastructure apply. Alert when a plugin with hooks or MCP loads from an unexpected source.

Tool Decisions Are The Core Control Signal

The tool_decision event is the center of Claude Code control observability. It records whether a tool call was accepted or rejected and where the decision came from. That source can indicate config, hook, temporary user approval, permanent user approval, user abort, or user rejection.

This matters because the same action has different risk depending on the source. A command allowed by managed config may be expected. A command allowed by a user-permanent setting may indicate a local exception. A command blocked by a hook may indicate a successful control. A rejected tool call may indicate an attempted unsafe path or a confused workflow.

Dashboards should separate accepted and rejected decisions by tool type, repository, user, branch, permission mode, and decision source. Repeated user approvals for the same high-risk command should become a policy review. Repeated hook blocks should become a developer education or rule-tuning task.

MCP Observability

MCP observability requires both connection events and tool-result detail. The connection event tells you that a server connected, disconnected, or failed. Tool-result events tell you which MCP tool was called and what arguments were passed when tool details are enabled.

Enable OTEL_LOG_TOOL_DETAILS=1 when the enterprise needs MCP audit coverage. Without it, you still see broad MCP activity, but you lose the exact server and tool breakdown that most investigations need.

MCP dashboards should answer these questions.

• Which MCP servers are active across the fleet?
• Which servers are user-scoped, project-scoped, local, or managed?
• Which servers failed to connect repeatedly?
• Which MCP tools are used most often?
• Which repositories use broad or privileged MCP tools?
• Which MCP calls were denied by config, hook, or user rejection?
• Which MCP tool results correlate with later Bash commands or file edits?

MCP tool output should be treated as untrusted input. Observability should show when an MCP call preceded a sensitive action such as a secret read, workflow edit, deploy command, or database operation. That correlation is where logs and traces become useful together.

Hook Observability

Hooks are control code, so they need their own observability. Claude Code emits hook registration and execution events. Those events let security teams inventory which hooks are present, where they came from, how long they took, and whether they returned blocking decisions.

Useful hook alerts include:

• A protected repository starts without the expected managed hooks.
• A hook source changes from policy settings to a merged or local source.
• A hook that normally blocks risky commands stops running.
• A hook returns repeated non-blocking errors.
• A hook blocks a deployment command, workflow edit, MCP configuration change, or secret read.
• A plugin hook appears from an unexpected marketplace or scope.

Hooks should emit structured decisions into the same backend. The hook event tells you that a hook ran. The hook's own output can preserve the normalized command, path, policy rule, reason, and reviewer instructions. Keep the output small enough for the telemetry pipeline and stable enough for detection rules.

Permission Mode Observability

Permission mode changes are high-value events. A shift from plan mode into default can be ordinary. A shift into bypass permissions on a developer laptop is a security event. A non-interactive job that runs in a permissive mode deserves scrutiny.

Create alerts for these cases:

• to_mode equals bypassPermissions outside approved containers or CI profiles.
• A sensitive repository exits plan mode and immediately requests a high-risk Bash command.
• A permission-mode change happens shortly before a package publish, infrastructure apply, database migration, or deploy command.
• Auto mode gates deny a transition repeatedly for the same repository or user.

Mode alerts should include repository tier, user, device or workspace, active managed settings profile, and recent tool decisions. That context separates legitimate workflow changes from risky escalation.

Traces And The Agent SDK

Traces are useful when teams need causality. Claude Code tracing links a user interaction to API requests, tool calls, permission waits, tool execution, hooks, and subagent work. The Agent SDK observability path also matters because embedded Claude Code processes can participate in a larger application trace.

For Agent SDK and non-interactive claude -p sessions, Claude Code can read inbound W3C trace context from TRACEPARENT and TRACESTATE. That lets a parent service pass trace context into the Claude Code subprocess so the Claude Code interaction appears under the caller's trace. Interactive sessions are treated differently to avoid accidental inheritance from ambient shell or CI values.

When tracing is active, Bash and PowerShell subprocesses can inherit TRACEPARENT for the active tool execution span. That enables scripts and commands run by Claude Code to attach their own spans to the same distributed trace if they are instrumented.

Use traces for these workflows:

• Agent SDK applications that call Claude Code inside a larger product workflow.
• CI jobs where the parent workflow trace should include Claude Code actions.
• Incident investigations that need prompt-to-tool causality.
• Latency analysis for model calls, hooks, permission waits, tool execution, and subagents.
• Regression tests that need to prove a risky chain stopped at the expected layer.

Keep trace content fields conservative. Traces can become extremely sensitive when prompt text, tool input, tool output, and raw API bodies are enabled. Metadata-first traces are usually enough for operational causality. Content-bearing traces need restricted storage, access review, and retention limits.

Collector And SIEM Routing

The OpenTelemetry Collector should be treated as the control point for Claude Code telemetry. It can receive OTLP, authenticate clients, attach resource attributes, redact fields, route metrics and logs separately, and forward to multiple backends.

A common architecture looks like this:

Use OTEL_RESOURCE_ATTRIBUTES to attach team, department, cost center, environment, repository tier, workspace type, or deployment profile. Keep the formatting strict because OpenTelemetry resource attributes have specific key-value requirements.

Avoid a single sink for every signal. Metrics often belong in a time-series or observability backend. Security events belong in the SIEM. Traces belong in a tracing backend. Raw body evidence, when enabled, belongs in restricted storage with a short retention policy.

Privacy And Data Minimization

Claude Code observability can expose sensitive data if configured carelessly. Prompt text may include unreleased code, credentials pasted by mistake, customer data, or regulated data. Tool input can include file paths, search terms, URLs, Bash commands, MCP arguments, and other workflow details. Tool output can include raw file contents and command output.

Use a tiered privacy posture.

Privacy review should define who can query the data, which fields are redacted, how long each field is retained, which repositories permit detailed logging, and how DSAR or deletion workflows apply to telemetry. The retention policy should be shorter for content-bearing streams than for aggregate metrics.

The safest rule is practical. Collect the minimum detail needed to answer a security question, and collect richer detail only where the control objective requires it.

Dashboards That Matter

Claude Code dashboards should serve security and platform operations, not vanity reporting.

Dashboards should let teams drill from aggregate view to individual session. A cost spike should lead to the sessions that caused it. A hook failure should lead to the repository and command. An MCP anomaly should lead to server, tool, user, and prompt ID.

Detection Rules

Start with high-signal detections.

Each alert should have a runbook. The runbook should state the query, expected fields, severity, owner, investigation steps, containment steps, and regression test to add after remediation.

Incident Response Workflow

When a Claude Code incident occurs, start with the prompt ID or session ID. Use that key to reconstruct the sequence.

1. Identify user, repository, branch, workspace type, and permission mode.
2. Pull the user_prompt, api_request, tool_decision, tool_result, mcp_server_connection, and hook events for the same prompt or session.
3. Confirm whether the risky action was allowed, denied, blocked by hook, or rejected by the user.
4. Inspect downstream effects such as file edits, commits, pull requests, package publishes, deployments, database operations, or external uploads.
5. Contain the path by updating permissions, hooks, MCP allowlists, proxy rules, credentials, or CI gates.
6. Turn the incident into a regression test.

Good observability shortens this workflow. Without prompt IDs, tool IDs, MCP server names, hook decisions, and branch metadata, the investigation becomes guesswork.

CI/CD And Non-Interactive Observability

Non-interactive Claude Code jobs need stronger observability than local sessions. A CI job can run without a human present to judge a prompt. The event stream should prove that the job stayed inside its intended boundary.

CI telemetry should include workflow name, job ID, repository, branch, commit, actor, permission profile, container image, managed settings version, tool decisions, hook results, MCP servers, and output artifact. If the job opens a pull request, connect the pull request number to the session ID.

For CI, traces are valuable because they let teams connect the parent workflow to the Claude Code interaction. If the CI orchestration system already emits traces, pass W3C trace context into the Claude Code process for non-interactive sessions. That gives release engineering a single trace that covers job start, Claude Code model call, tool calls, test execution, artifact creation, and PR creation.

The CI policy should alert when Claude Code attempts a protected branch push, package publish, infrastructure apply, database migration, or production deploy. The ideal output is a reviewed pull request with evidence, not an unreviewed production effect.

Agent SDK Observability

Agent SDK observability matters when Claude Code is embedded inside another application or automation system. The parent application may have its own trace, request ID, tenant ID, workflow ID, and user identity. Claude Code should appear inside that same flow with trace context, parent span linkage, and shared incident metadata.

Use inbound trace context for non-interactive and Agent SDK sessions. Attach application metadata through resource attributes. Preserve the link between parent workflow ID and Claude Code session ID. Route Claude Code spans to the same tracing backend used by the application when the privacy policy allows it.

For product teams, the useful questions are:

• Which application workflow invoked Claude Code?
• Which user or tenant initiated the workflow?
• Which model requests and tool calls happened under that workflow?
• Which permission decisions delayed or blocked the workflow?
• Which hook or MCP event explains the outcome?
• Did the workflow produce a commit, pull request, ticket, or deployment artifact?

The Agent SDK observability design should make those answers queryable.

Backend Selection

Choose backends based on the questions they answer.

Metrics backends such as Prometheus-style systems are good for rates, trends, and dashboards. Log and event backends such as Elasticsearch, Loki, ClickHouse, or a SIEM are good for security queries and audit trails. Trace backends such as Jaeger, Tempo, Zipkin, Honeycomb, or Datadog are good for causality and latency analysis.

For security programs, the SIEM path matters most. Claude Code events should join identity logs, endpoint logs, source-control logs, CI logs, cloud logs, and proxy logs. A Bash command is more useful when it can be correlated with a GitHub workflow, cloud API call, or endpoint network event.

For platform programs, the metrics path matters. Cost, token usage, sessions, active time, commits, pull requests, and lines changed can guide rollout and identify friction.

For engineering programs, the trace path matters. Traces help teams understand where time went and why an automation failed.

OpenTelemetry Rollout Plan

Roll out Claude Code observability in phases.

Phase 1: Local pipeline

Enable metrics and logs on a test machine. Send OTLP to a local collector. Run safe commands, rejected commands, MCP connections, and hook events. Confirm the expected events appear.

Phase 2: Managed settings

Move the configuration into managed settings. Confirm users cannot override the endpoint or disable required telemetry in protected environments. Add resource attributes for team, department, repository tier, and workspace type.

Phase 3: SIEM integration

Forward logs/events into the SIEM. Build initial detections for permission-mode escalation, risky Bash, unapproved MCP, hook failures, plugin installation, and API errors. Create runbooks.

Phase 4: Privacy review

Decide whether to enable OTEL_LOG_TOOL_DETAILS, prompt logging, tool content, or raw API bodies. Implement redaction at the collector or backend. Define retention and access.

Phase 5: Tracing

Enable traces for Agent SDK, CI, and incident reconstruction workflows. Validate TRACEPARENT propagation and confirm spans are connected to parent application traces where intended.

Phase 6: Regression loop

Turn incidents, red-team findings, and policy failures into repeatable tests. Use telemetry to prove the control acts at the expected layer.

Common Mistakes

The first mistake is enabling detailed logging without a privacy decision. Tool arguments and prompt content can contain sensitive values.

The second mistake is collecting events without detections. A SIEM feed that nobody queries has limited value. Start with a small set of high-signal alerts and improve them from real incidents.

The third mistake is treating metrics as audit logs. Metrics are good for trends. Events and traces are better for investigations. Compliance evidence may also require Anthropic audit logs or the Compliance API for account and resource lifecycle events.

The fourth mistake is ignoring MCP. MCP servers are tool boundaries. Without MCP connection and tool events, the enterprise cannot explain which server was used or which action it exposed.

The fifth mistake is forgetting hooks. Hooks are control code. If hooks block sensitive actions, their registration, source, execution, failures, and blocking decisions should be monitored.

How General Analysis Helps

General Analysis helps teams connect Claude Code observability to AI Detection and Response. The platform correlates prompts, repository context, Bash, MCP, hooks, browser and web fetch, managed settings, CI/CD, and multi-step agent workflows into incidents that security teams can investigate and contain.

General Analysis AI Detection and Response uses telemetry-backed traces to identify whether risky actions were blocked, escalated, or allowed. The same traces support policy tuning, incident review, and response workflows that block, redact, require approval, quarantine a session, or route an action through a safer path.

Related Claude Code Guides

For the full deployment model, read How to Secure Claude Code. For the control checklist, read Anthropic Claude Code Security Best Practices. For configuration details, read Claude Code Settings, Permissions, and Bash Tool Security. For enterprise rollout planning, read Claude Code Enterprise Security Deployment. For Anthropic audit coverage beyond Claude Code OTel, read How to Audit Claude with the Compliance API.