> For the complete documentation index, see [llms.txt](https://handbook.harmonic.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://handbook.harmonic.security/handbook/6.-observability-audit-and-evidence/6.2-opentelemetry-for-ai-runtime-visibility.md). # 6.2 OpenTelemetry for AI runtime visibility How to use OpenTelemetry for AI runtime visibility across Work, Cowork, Codex, Claude Code, Copilot, Grok, and adjacent evidence sources. *Last reviewed: August 18, 2026* {% hint style="info" %} OpenTelemetry gives you visibility. It can feed alerting and investigations, but it does not block an agent action by itself. {% endhint %} ## The short version OTel, short for OpenTelemetry, is the common pipe for traces, logs, and metrics. In AI runtime security, it is useful because it can connect the user request, model call, tool call, approval decision, file access, connector call, error, and final outcome into one timeline. That makes OTel a **visibility** control. It helps you answer what happened, who initiated it, which runtime acted, which tool was called, what policy decision was made, and where the downstream action landed. It becomes a practical control only when you use it to drive detections, alerts, approvals, investigations, and response playbooks. OTel is also not vendor-specific. It is an open standard, and AI runtimes across the market are converging on it: Claude Cowork and Claude Code, OpenAI Codex, GitHub Copilot (enterprise-managed export for the VS Code extension and CLI), and xAI's Grok Build (its own exporter, emitting token, turn, tool call, and error metrics plus per-session OTLP log records) all ship OTel export today. That means one collector pipeline can serve every runtime you deploy, and OTel skills transfer across vendors. The main risk is content. Prompts, tool arguments, file names, file snippets, API responses, and connector payloads can contain secrets or regulated data. Do not stream everything into a broad SIEM index just because the vendor can export it. Put an OTel Collector or equivalent processing layer in the path, redact before ingestion, and keep raw content in a restricted evidence store only when you have a clear reason. ## What it gives you | Security value | What OTel gives you | What it does not give you | | -------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Visibility | Structured logs, traces, metrics, correlation IDs, timing, tool calls, errors, and sometimes prompts and file activity. | It does not stop the action while it is happening. | | Investigation | A timeline across prompt, model, tool, approval, target system, and result. | It does not replace endpoint, SaaS, Slack, GitHub, M365, browser, or network evidence. | | Detection | High-signal events for risky tools, denied actions, unusual connectors, data access, and policy drift. | It does not guarantee completeness unless you test source-to-SIEM delivery. | | Governance | Adoption, activity, policy outcome, and exception evidence. | It does not prove safe use unless the schema, retention, and redaction rules are documented. | ## OTel vs the Compliance API (Anthropic) Anthropic gives you two ways to see what Claude did, and they sit on different plans: OTel is available on both Team and Enterprise, while the Compliance API is Enterprise only. If you are on Team, OTel is your only feed, so treat it as such. If you are on Enterprise, the two answer different questions, and you should plan for both rather than pick one. **OTel is the wire. The Compliance API is the record.** OTel pushes structured events to your collector in real time as sessions run. The Compliance API is a pull interface over content Anthropic stores server-side: full session transcripts for Cowork and Claude Code, plus claude.ai chats, files, artifacts, and projects, retained for 6 years by default (or your configured retention period). Anthropic explicitly supports running both in parallel. | Dimension | OTel | Compliance API | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Model | Push. Real-time event stream to your OTLP collector. | Pull. Query stored content after the fact with a Compliance Access Key. | | Plan | Team and Enterprise. | Enterprise only. Session transcript endpoints are in beta. | | Content depth | Metadata by default. Prompt text, response text (60 KB cap), and tool inputs (\~4 KB cap) only when an admin enables them via `otlpContentCapture`. | Full reconstructed transcripts: prompts, assistant text, tool calls, and full tool results up to roughly 1 MiB per block. Thinking blocks, system prompts, and binary content are excluded from transcripts. | | Unique data | Token counts, estimated cost per request, execution durations, API errors and retries, and permission decisions with their source (config, hook, user). | Full tool result content, downloadable file and artifact binaries, claude.ai chat and project content, and hard-delete endpoints for chats, files, and projects (eDiscovery, legal hold, deletion requests). Sessions themselves are read-only. | | History | None. If your collector was not listening, the event is gone. | 6-year retrieval by default, walkable and resumable via cursors. | | Coverage | Any session on a configured client version. Requires the OTLP endpoint to be set before the session starts. | Does not capture Claude Code via Console API keys or Bedrock/Vertex, HIPAA-enabled orgs, or ZDR sessions. Local transcripts show only what reached the API, not on-device activity. | The practical split: route OTel into your SIEM for **detection and alerting** (approval denials, risky tool use, cost anomalies, telemetry source health), and treat the Compliance API as the **authoritative audit and retrieval layer** for investigations, eDiscovery exports, DLP review, and deletion obligations. Neither is a superset of the other: transcripts carry no token, cost, duration, or approval-decision data, and OTel carries no file binaries and no history. One trap to avoid: because OTel is metadata-only by default and the Compliance API captures transcripts server-side regardless, an Enterprise org that never enables `otlpContentCapture` still has full prompt and tool content sitting in the Compliance API. Retention, access, and legal review plans need to cover both paths. ## Product support | Product | OTel support | What security gets | Watch-outs | | ---------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude Cowork | Yes for Team and Enterprise in the current documentation. | Prompts, tool and MCP calls, file access, skills and plugins, approval decisions, API requests, errors, and shared prompt identifiers. | Content capture (prompts, responses, tool inputs) is gated by the `otlpContentCapture` setting; validate what is enabled before routing to a broad index. Cowork and Claude Code sessions are also retrievable through Anthropic's Compliance API on Enterprise; see the section above. | | Claude Code | Yes. | Logs, metrics, and traces through environment variables or managed settings, with optional prompt and tool-detail logging. | Prompt content is off by default for a reason. Managed settings are the right enforcement layer for teams. | | Claude Tag | No OTel feed in the reviewed docs. | Use Tag Audit, Agent Proxy network events where enabled, Slack records, service-account logs, and connected-system logs. | Do not treat absence from the OTel collector as absence of Tag activity. | | ChatGPT Codex | Yes for local Codex configuration. | Runtime traces or logs from Codex local, useful for tool calls, approvals, errors, and local execution context where configured. | Codex user-level configuration matters. Raw prompt logging is an explicit opt-in and should stay off unless privacy and legal approve. | | ChatGPT Work | No native hosted Work OTel feed in the reviewed guides. | Use ChatGPT Compliance Logs for prompts and responses, workspace analytics, endpoint telemetry, connector logs, source-system audit logs, and Codex OTel where Work uses local Codex-adjacent execution. | Compliance Logs may not include files, actions, or tool calls. Hosted Work and local Codex need separate evidence plans. | | Grok Build (xAI) | Yes, via its own OTel exporter. | Metrics under the `ai.xai.grok_code` meter scope covering token usage, turns, tool calls, errors, and startup timings, plus structured per-session events as OTLP log records. | Nothing is emitted unless both the `GROK_EXTERNAL_OTEL` master switch and at least one exporter are configured. Verify the feed exists before assuming coverage. | | GitHub Copilot | Yes, enterprise-managed export for the VS Code Chat extension and Copilot CLI. | Centrally mandated OTLP endpoint, protocol, service name, resource attributes, and exporter headers through enterprise settings. | Coverage is scoped to the surfaces GitHub documents; other Copilot surfaces need their own evidence plan. | ## How to use it technically Put a collector between the AI runtime and the destination. That gives you one place to normalize fields, redact content, route high-risk events, and detect broken sources. A practical OTel pipeline has five parts: 1. **Runtime exporter.** Configure Claude Code, Claude Cowork, Codex, Copilot, Grok Build, or another runtime to export telemetry to an OTLP endpoint. 2. **Collector.** Receive OTLP over HTTP or gRPC. Use processors to redact, drop, transform, batch, and route events. 3. **Restricted evidence store.** Keep sensitive prompt or tool content here only if the business, legal, and privacy teams agree it is needed. 4. **SIEM or data lake.** Send normalized metadata, high-risk events, and approved redacted fields for broad search and detection. 5. **Correlation layer.** Join OTel events with endpoint, IdP, GitHub, Slack, M365, browser, DLP, network, and source-system logs. For Claude Code, the technical switch usually starts with telemetry enabled and OTLP exporters configured. A simple pattern is: {% code collapsedlinecount="10" %} ```bash CLAUDE_CODE_ENABLE_TELEMETRY=1 OTEL_LOGS_EXPORTER=otlp OTEL_TRACES_EXPORTER=otlp OTEL_METRICS_EXPORTER=otlp OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com ``` {% endcode %} Use managed settings to distribute this for enterprise users, and keep prompt and tool-content flags disabled unless you have a redaction and retention design. For Claude Cowork, configure OTel from the organization Cowork settings and send it to a standard OTel Collector. Validate whether prompts and tool parameters are included before connecting it to a shared logging destination. For Codex, configure OTel in the user-level Codex configuration, not only in a repo-local file. Treat prompt logging as a separate data decision. The safe default is metadata first, prompt content later only if approved. ## Minimum AI event schema Normalize vendor events into one schema. You do not need every field on day one, but you need the same shape across products. | Field group | Minimum fields | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | Event | Event type, schema version, event time, ingestion time, source, environment. | | Identity | User, group, agent or service identity, tenant or workspace, project. | | Execution | Product, surface, local or hosted runtime, task ID, trace ID, parent task, model, policy version. | | Action | Tool or capability, target system, target object, argument classification, approval requirement, approval decision. | | Outcome | Result, error, retry, duration, token count, spend, stop reason, cancellation state. | | Evidence | Redaction state, source record ID, downstream record ID, retention class. | Keep raw prompts out of the shared schema by default. Store hashes, classifications, token counts, prompt IDs, or restricted links when that is enough. ## How to use it as a practitioner Start with the questions a security team needs to answer during rollout: * Who is using Work, Cowork, Code, Codex, and Tag? * Which tasks touched local files, browser sessions, connectors, Slack, M365, GitHub, or production systems? * Which actions required approval, and which were denied? * Which MCP servers, plugins, skills, hooks, and browser sessions appeared in the trace? * Did a scheduled or unattended task do anything that would have required a human in a live session? * Can an investigator connect the AI event to the downstream SaaS, endpoint, repository, or ticket record? Build dashboards around those answers, not around generic token charts. Good first dashboards are: high-risk tool use, approvals and denials, connector reads and writes, file access by data class, sandbox mode distribution, network egress attempts, scheduled tasks, prompt-content logging status, and telemetry source health. Then test the pipeline with canary actions. Run a safe denied read, a safe blocked network request, a safe approved file edit, a safe connector read, and a safe tool failure. Confirm each event appears at the runtime, collector, destination, and investigation view. Repeat this after product upgrades, collector changes, schema changes, and new policy releases. ## Redaction stance The collector should remove or transform sensitive content before broad export. Use OpenTelemetry processors, including redaction or transform processors where appropriate, to drop sensitive attributes, mask secrets, and route high-risk records to a narrower destination. Redaction after SIEM ingestion is too late. At that point, the content has already been stored, indexed, searched, and possibly copied into alerts. A clean starting policy is: * Store prompt text only in a restricted evidence store, and only for approved groups or incident workflows. * Send prompt IDs, hashes, classifications, model names, and tool names to the SIEM. * Drop secret-like values from tool arguments before indexing. * Keep file contents out of telemetry unless there is a specific, documented investigation need. * Alert on telemetry configuration drift, source silence, collector errors, and unexpected prompt-content logging. ## What to avoid * Do not assume Compliance Logs, OTel, endpoint logs, and connector logs contain the same events. They rarely do. * Do not sample away approval, denial, file access, connector write, hook, or sandbox-denial events. * Do not use one retention rule for every field. Metadata and prompt content usually need different retention and access. * Do not treat a clean OTel dashboard as proof of clean AI use until you have tested source completeness. * Do not let agents edit their own telemetry configuration or collector routing. ## Sources and related guidance * [Securing ChatGPT Work: A Practitioner's Guide](https://www.harmonic.security/resources/securing-chatgpt-work-a-practitioners-guide) * [Securing Claude Cowork: A Security Practitioner's Guide](https://www.harmonic.security/resources/securing-claude-cowork-a-security-practitioners-guide) * [Monitor Claude Cowork activity with OpenTelemetry](https://support.claude.com/en/articles/14477985-monitor-claude-cowork-activity-with-opentelemetry) * [Cowork monitoring reference (OTel events and attributes)](https://claude.com/docs/cowork/monitoring) * [Anthropic Compliance API: retrieve session transcripts](https://platform.claude.com/docs/en/manage-claude/compliance-sessions) * [Anthropic Compliance API: retrieve and delete chats, files, and projects](https://platform.claude.com/docs/en/manage-claude/compliance-content-data) * [Claude Code monitoring](https://code.claude.com/docs/en/monitoring-usage) * [Codex configuration reference](https://developers.openai.com/codex/config-reference) * [ChatGPT Work and Codex](https://help.openai.com/en/articles/20001275-chatgpt-work-and-codex) * [Grok Build OpenTelemetry monitoring (SigNoz)](https://signoz.io/docs/grok-build-observability/) * [Enterprise-managed OpenTelemetry export for VS Code and CLI (GitHub changelog)](https://github.blog/changelog/2026-07-08-enterprise-managed-opentelemetry-export-for-vs-code-and-cli/) * [OpenTelemetry Collector processors](https://opentelemetry.io/docs/collector/components/processor/) * [OpenTelemetry Collector redaction processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/redactionprocessor/README.md) ## Related handbook guidance * [6. Observability, Audit & Evidence](/handbook/6.-observability-audit-and-evidence.md) * [6.3 Compliance APIs by platform](/handbook/6.-observability-audit-and-evidence/6.3-compliance-apis-by-platform.md) * [6.5 Routing AI telemetry to your SIEM](/handbook/6.-observability-audit-and-evidence/6.5-routing-ai-telemetry-to-your-siem.md) * [6.6 Evidence by surface and investigation paths](/handbook/6.-observability-audit-and-evidence/6.6-evidence-by-surface-and-investigation-paths.md) * [2.6 AI hooks: inference controls and lifecycle automation](/handbook/2.-supply-chain-and-extensibility/2.6-ai-hooks-inference-controls-and-lifecycle-automation.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://handbook.harmonic.security/handbook/6.-observability-audit-and-evidence/6.2-opentelemetry-for-ai-runtime-visibility.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.