@anthropic-ai/claude-trace

OTEL Viewer

A Node.js server that receives OpenTelemetry logs and traces via HTTP, organizing them by session and storing them locally.

Setup

npm install

Running the Server

npm start

The server will start on http://localhost:4318 (default OTEL collector port).

Configuration

Set environment variables to customize the server:

• PORT - Server port (default: 4318)

Using with Claude Code

Configure Claude Code to send logs to this server:

export ENABLE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_MODEL_RESPONSE=1
export OTEL_LOG_TOOL_CONTENT=1

Then run Claude Code normally:

claude --help
# Your commands here

API Endpoints

POST /v1/logs

Receive OTEL logs and store them organized by session.

Request:

{
  "traceId": "abc123...",
  "spanId": "def456...",
  "resourceLogs": [...]
}

Response:

{
  "status": "ok",
  "sessionId": "abc123..."
}

POST /v1/traces

Alternative endpoint for OTEL traces (same behavior as /v1/logs).

GET /health

Health check endpoint.

Response:

{
  "status": "ok",
  "dataDir": "/path/to/data"
}

GET /sessions

List all sessions with their metadata.

Response:

{
  "sessions": [
    {
      "sessionId": "abc123...",
      "lastUpdated": "2024-01-15T10:30:45.123Z",
      "logCount": 42
    }
  ]
}

GET /sessions/:sessionId

Retrieve all logs for a specific session.

Response:

{
  "sessionId": "abc123...",
  "logs": [
    {
      "timestamp": "2024-01-15T10:30:45.123Z",
      "traceId": "abc123...",
      "spanId": "def456...",
      "sessionId": "abc123...",
      "content": {...}
    }
  ]
}

GET /sessions/:sessionId/export

Export all logs for a session as a JSON file.

Viewing Logs

Use the CLI viewer to browse stored logs:

# List all sessions
npm run view

# View session summary
npm run view view <sessionId>

# View raw session data as JSON
npm run view raw <sessionId>

Data Storage

Logs are stored in the data/ directory:

data/
├── session-1-abc123/
│   ├── logs.jsonl          # All logs for this session (one JSON per line)
│   └── summary.json        # Session metadata
├── session-2-def456/
│   ├── logs.jsonl
│   └── summary.json
└── ...

Each session directory contains:

• logs.jsonl - JSONL format (one JSON object per line) for efficient streaming
• summary.json - Metadata about the session

Development

# Start with auto-reload
npm run dev

# Build TypeScript
npm run build

Session ID Detection

The server automatically extracts session IDs from:

• traceId field (primary identifier)
• resourceLogs[0].resource.attributes['session.id']
• resourceLogs[0].scopeLogs[0].logRecords[0].attributes['session.id']

If no session ID is found, logs are stored under unknown/.

Typical Workflow

• Start the server:

  npm start
  

• Configure Claude Code with environment variables (see above)

• Run Claude Code normally:

  claude your-command
  

• View collected logs:

  npm run view
  npm run view view <sessionId>
  

• Export for analysis:

  curl -o session-data.json http://localhost:4318/sessions/<sessionId>/export
  

Notes

• Logs are stored in JSONL format for efficient streaming and parsing
• Each session is stored in its own directory for easy organization
• The server creates the data/ directory automatically
• All timestamps are in ISO 8601 format
• Request body size limit is 50MB per request