Tracing & Verbose Logging

Enable detailed logging to debug Codex behavior and troubleshoot issues

Overview

Codex provides comprehensive tracing and logging capabilities to help you understand what’s happening under the hood. This is especially useful for:

• Debugging unexpected behavior
• Troubleshooting integration issues
• Understanding performance characteristics
• Filing detailed bug reports

Verbose logging can generate large amounts of output and may include sensitive information. Use with caution in production environments.

Quick Start

Enable verbose logging with the RUST_LOG environment variable:

# Basic verbose logging
RUST_LOG=debug codex

# Trace-level logging (very verbose)
RUST_LOG=trace codex

# Info-level logging (default for Codex crates)
RUST_LOG=info codex

RUST_LOG Environment Variable

The RUST_LOG variable controls logging verbosity using the standard Rust tracing infrastructure.

Log Levels

error · level

Only critical errors that prevent operation

warn · level

Warning messages about potential issues

info · level

High-level informational messages (default for Codex crates)

debug · level

Detailed debugging information

trace · level

Extremely verbose tracing output

Syntax

Global Level

Set the same level for all modules:

RUST_LOG=debug codex

Per-Module

Set different levels for specific modules:

# Debug Codex core, info for everything else
RUST_LOG=info,codex_core=debug codex

# Trace exec module, debug for core
RUST_LOG=codex_exec=trace,codex_core=debug codex

Pattern Matching

Use patterns to target specific modules:

# Debug all codex-* crates
RUST_LOG=codex=debug codex

# Trace specific function
RUST_LOG=codex_core::agent::process_event=trace codex

Common Logging Scenarios

Debug API Requests

# See all API request/response details
RUST_LOG=codex_core::api=debug codex

Output includes:

• Request URLs and headers
• Request body payloads
• Response status codes
• Response bodies
• Timing information

Debug File Operations

# Trace file reading, writing, and patching
RUST_LOG=codex_core::files=debug codex

Shows:

• Files being read
• Patches being applied
• File system operations
• Permission checks

Debug Command Execution

# See all shell commands and output
RUST_LOG=codex_exec=debug codex exec "run tests"

Includes:

• Commands being executed
• Working directory
• Environment variables
• stdout/stderr output
• Exit codes

Debug Sandboxing

# Trace sandbox setup and policy enforcement
RUST_LOG=codex_sandbox=debug,codex_process_hardening=debug codex

Reveals:

• Sandbox initialization
• Policy rules being applied
• Permission checks
• Blocked operations

Exec Mode Logging

In exec mode, logs are written to a file to avoid interfering with output:

Log File Location

By default, logs are written to:

~/.codex/logs/codex-tui-<timestamp>.log

Enable File Logging

Logs are automatically written to file when you set RUST_LOG:

RUST_LOG=debug codex exec "analyze code"

# Check the log file:
tail -f ~/.codex/logs/codex-tui-*.log

Log Rotation

Log files are rotated automatically. Old logs are kept for debugging but can be safely deleted.

OpenTelemetry Integration

Codex supports OpenTelemetry for distributed tracing:

Configuration

~/.codex/config.toml

[otel]
enabled = true
endpoint = "http://localhost:4317"  # OTLP gRPC endpoint

# Optional: Sample rate (0.0 to 1.0)
sampling_ratio = 1.0

# Optional: Service name
service_name = "codex-cli"

Environment Variables

Alternatively, use standard OTEL env vars:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_TRACES_SAMPLER="always_on"

codex

Viewing Traces

Use Jaeger or another OTEL-compatible backend:

1. Start Jaeger

   docker run -d --name jaeger \
     -p 4317:4317 \
     -p 16686:16686 \
     jaegertracing/all-in-one:latest
   
2. Configure Codex

   export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
   codex
   
3. View Traces

   Open http://localhost:16686 in your browser

Legacy TypeScript CLI

For the legacy TypeScript implementation, use DEBUG:

# Full API request/response logging
DEBUG=true codex

The TypeScript CLI is deprecated. Consider migrating to the Rust implementation for better performance and features.

Practical Examples

Debug slow performance

# Enable timing information
RUST_LOG=debug,codex_core::timing=trace codex

Look for:

• API request latency
• File I/O timing
• Long-running operations

Debug authentication issues

# Trace auth flow
RUST_LOG=codex_core::auth=debug,codex_api::auth=debug codex

Shows:

• Token acquisition
• Token refresh attempts
• Authentication errors
• API key validation

Debug MCP integration

# Trace MCP server communication
RUST_LOG=codex_core::mcp=debug codex

Reveals:

• MCP server initialization
• Tool calls and responses
• Connection errors
• Message parsing

Debug config loading

# Trace config resolution
RUST_LOG=codex_core::config=debug codex

Displays:

• Config file locations checked
• Loaded configuration values
• Override application
• Validation errors

Full diagnostic logging

# Everything at debug level
RUST_LOG=codex=debug codex 2>&1 | tee codex-debug.log

Captures all Codex modules at debug level and saves to file.

Performance Considerations

Log Level Impact

Higher log levels (trace/debug) can slow down execution by 10-50%

File I/O Overhead

Writing logs to disk adds latency, especially with trace level

Memory Usage

Verbose logging increases memory usage for buffering

Network Tracing

OTEL tracing adds ~5-10ms per span to network requests

For production use, stick with info or warn level logging. Use debug or trace only for active troubleshooting.

Filtering Output

Grep for Specific Events

# Find all error messages
RUST_LOG=debug codex 2>&1 | grep ERROR

# Find API calls
RUST_LOG=debug codex 2>&1 | grep "http request"

# Find file operations
RUST_LOG=debug codex 2>&1 | grep "file:"

Focus on Specific Modules

# Only log Codex crates, silence dependencies
RUST_LOG=codex=debug codex

# Log multiple specific modules
RUST_LOG=codex_core=debug,codex_exec=info codex

Troubleshooting Logging

No logs appearing

• Verify RUST_LOG is set: echo $RUST_LOG
• Check log file location: ls -lh ~/.codex/logs/
• Try higher verbosity: RUST_LOG=trace
• Ensure Codex has write permissions to log directory

Too much output

• Lower the log level: RUST_LOG=info instead of debug
• Filter to specific modules: RUST_LOG=codex_core=debug
• Use grep to filter: RUST_LOG=debug codex 2>&1 | grep pattern

Logs missing expected info

• Increase verbosity: RUST_LOG=debug or RUST_LOG=trace
• Check you’re targeting the right module
• Some modules may not have debug logging implemented

Sensitive data in logs

• Codex attempts to redact secrets automatically
• Review logs before sharing publicly
• Use RUST_LOG=info in production to minimize exposure
• Set otel.sampling_ratio = 0.1 to reduce trace data

Filing Bug Reports

When reporting issues, include relevant logs:

1. Reproduce with Logging

   RUST_LOG=debug codex <your command> 2>&1 | tee codex-issue.log
   
2. Redact Sensitive Data

   Review the log file and remove:

   • API keys
   • Tokens
   • Personal information
   • Proprietary code
3. Attach to Issue

   Include the redacted log file when filing a GitHub issue:

   https://github.com/openai/codex/issues/new

Advanced Configuration

Custom Log Format

Codex uses tracing-subscriber for logging. You can customize the format:

# JSON format logs
RUST_LOG=debug RUST_LOG_FORMAT=json codex

# Compact format
RUST_LOG=debug RUST_LOG_FORMAT=compact codex

Span Tracing

View function call spans:

# Show span enter/exit events
RUST_LOG=trace codex

Output includes:

→ entering span: process_event
  ← exiting span: process_event (took 42ms)

See Also

Exec Mode

Non-interactive execution for automation

Configuration

Configure Codex behavior

Troubleshooting

Common issues and solutions

Contributing

Help improve Codex