Claude Code's Hidden Audit Trail: What Developers Need to Know About Logs, Metrics, and Traces
Claude Code leaves behind a complete digital record of every action it takes, and most developers don't realize it's already being saved to their computer. Every session generates a local transcript file containing prompts, tool calls, token usage, and execution timing. For teams that want deeper visibility, optional telemetry exports can send metrics and traces to monitoring platforms like Datadog, Grafana, or Jaeger.
Where Does Claude Code Actually Store Session Data?
By default, Claude Code writes a JSON Lines file (a text format where each line is a separate record) to a hidden directory on your machine. The file path follows this pattern: ~/.claude/projects/
This happens automatically with zero configuration required. No cloud uploads, no external services, no setup steps. The data stays on your local disk unless you explicitly enable telemetry export. Each line in the file represents a discrete event: a user prompt, an assistant response, a tool call, or a queue operation.
What Information Can You Actually Extract From These Files?
The local transcript contains several record types, but the most useful for investigation are user prompts, assistant responses, and queue operations. User records include your prompt text plus any tool results sent back after the agent called a function. Assistant records contain the model's response in Anthropic's native format, including thinking blocks, text output, and tool use calls. Each assistant record also includes per-turn token usage: input tokens, output tokens, cache read tokens, and cache creation tokens.
This means you can answer critical questions without any additional infrastructure. Did the agent actually do what you asked? How many tokens did it consume? Which tool call was slow? All of this information is already on disk, waiting to be queried. Developers can use command-line tools like jq to extract this data in seconds.
How to Query Claude Code Session Data Without Special Tools
- Total Output Tokens: Use jq to sum all output tokens across a session by filtering for assistant records and adding their token counts. This works with zero telemetry setup and gives you the exact cost of a session in seconds.
- Tool Call History: Extract every tool the agent called in order by filtering assistant records for tool_use content blocks. This shows you the exact sequence of actions the agent took and what inputs it passed to each tool.
- Timing and Queue Events: Reconstruct when a prompt was submitted versus when processing actually began by examining queue-operation records. This reveals whether delays came from the model, the tools, or the user's own workflow.
These queries require only jq, a lightweight command-line JSON processor, and take seconds to run. No collector, exporter, or external service is needed. The data is already on disk in plain text format.
What About Deeper Telemetry and Monitoring?
For teams that want to track Claude Code usage across multiple developers or integrate with existing monitoring infrastructure, Anthropic supports OpenTelemetry (OTel), an open standard for collecting metrics, logs, and traces. OTel export is disabled by default, but enabling it requires only a few environment variables and a collector endpoint.
OpenTelemetry provides three signal types that work together. Traces are trees of spans that describe a unit of work, such as a session or model call, showing timing and parent-child relationships. Metrics are aggregated numbers over time, such as token counts, cost, or number of sessions. Logs are individual structured events that can include trace IDs and span IDs, allowing you to jump from a log entry back to the related trace.
Claude Code exports metrics in stable form, including session counts by start type (fresh, resume, continue, or agents_view), token usage by model and query source, USD cost with agent and skill names, lines of code added and removed by language, git activity, code edit acceptance rates, and active time split between user typing and agent work.
What Metrics and Events Does Claude Code Track?
- Session Metrics: Claude Code counts sessions started by type, distinguishing between fresh starts, resumed sessions, continued sessions, and sessions viewed in the agents interface. This helps teams understand how developers are using the tool.
- Token and Cost Tracking: The system records input tokens, output tokens, cache read tokens, and cache creation tokens by model and query source. It also calculates USD cost with dimensions for agent name, skill name, and MCP server name, enabling precise cost allocation.
- Code Quality Signals: Claude Code tracks lines of code added and removed by language, git commits and pull requests, and the accept/reject rate for code edits by decision source (hook, user, or config). This reveals how much of the agent's work developers actually keep.
- Permission and Tool Decisions: The system logs every permission decision, tool call, and API request, including which tool was called, how long it took, whether it succeeded, and the size of the input. This creates an audit trail of what the agent was allowed to do and what it actually did.
Events provide more granular detail than metrics. Claude Code logs user prompts (redacted by default), tool results with duration and success status, API requests and errors with model, cost, token counts, and latency, and permission mode changes showing who approved an action and how.
How Should Teams Handle Sensitive Data in Claude Code Logs?
The local transcript files can contain full prompts, tool inputs and outputs, and file contents in plain text. Anthropic treats these files as sensitive and recommends careful handling. By default, telemetry export redacts prompt text, response text, and tool arguments. Teams can opt in to specific categories by setting environment variables: OTEL_LOG_USER_PROMPTS to include prompt text, OTEL_LOG_ASSISTANT_RESPONSES to include response text, OTEL_LOG_TOOL_DETAILS to include tool names and arguments, and OTEL_LOG_TOOL_CONTENT to include full tool input and output bodies on trace spans.
This design allows teams to collect usage metrics and performance data without automatically exposing proprietary code, internal tool details, or sensitive business logic. Organizations can choose which categories of data to export based on their compliance and privacy requirements.
What Do Traces Add Beyond Logs and Metrics?
Traces are currently in beta and require an additional flag to enable. They provide a hierarchical view of a single user turn, showing the root interaction span, the LLM (large language model) request span with time-to-first-token and stop reason, hook execution spans, and tool execution spans broken down into time waiting for permission and actual execution time.
Claude Code uses W3C trace context standards, meaning traces can propagate across service boundaries. Bash subprocesses inherit a TRACEPARENT environment variable, allowing teams to connect Claude Code activity to downstream tool calls and infrastructure events. This integration with emerging OpenTelemetry GenAI semantic conventions means that GenAI-aware dashboards like SigNoz or Honeycomb can display Claude Code data without custom mapping.
For developers and platform engineers, this means Claude Code's observability is designed to integrate with existing monitoring stacks. Teams already using OpenTelemetry for other services can add Claude Code telemetry without learning new tools or building custom exporters.