Tracing & Verbose Logging

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
Per-Module
Pattern Matching

Set the same level for all modules:

RUST_LOG=debug codex

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

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:

Start Jaeger

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

Configure Codex

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
codex

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:

Reproduce with Logging

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

Redact Sensitive Data

Review the log file and remove:

API keys
Tokens
Personal information
Proprietary code

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)

Exec Mode

Non-interactive execution for automation

Configuration

Configure Codex behavior

Troubleshooting

Common issues and solutions

Contributing

Help improve Codex

Get Started

Core Concepts

Configuration

Features

Advanced Usage

Documentation Index

​Overview

​Quick Start

​RUST_LOG Environment Variable

​Log Levels

​Syntax

​Common Logging Scenarios

​Debug API Requests

​Debug File Operations

​Debug Command Execution

​Debug Sandboxing

​Exec Mode Logging

​Log File Location

​Enable File Logging

​Log Rotation

​OpenTelemetry Integration

​Configuration

​Environment Variables

​Viewing Traces

​Legacy TypeScript CLI

​Practical Examples

​Performance Considerations

Log Level Impact

File I/O Overhead

Memory Usage

Network Tracing

​Filtering Output

​Grep for Specific Events

​Focus on Specific Modules

​Troubleshooting Logging

​Filing Bug Reports

​Advanced Configuration

​Custom Log Format

​Span Tracing

​See Also

Exec Mode

Configuration

Troubleshooting

Contributing

Build docs developers (and LLMs) love

Overview

Quick Start

RUST_LOG Environment Variable

Log Levels

Syntax

Common Logging Scenarios

Debug API Requests

Debug File Operations

Debug Command Execution

Debug Sandboxing

Exec Mode Logging

Log File Location

Enable File Logging

Log Rotation

OpenTelemetry Integration

Configuration

Environment Variables

Viewing Traces

Legacy TypeScript CLI

Practical Examples

Performance Considerations

Filtering Output

Grep for Specific Events

Focus on Specific Modules

Troubleshooting Logging

Filing Bug Reports

Advanced Configuration

Custom Log Format

Span Tracing

See Also