Documentation

tracellm export

Export trace data for analysis and sharing.

Overview

The tracellm export command fetches recent traces from MongoDB and writes them to a file in JSON or CSV format. Exported data includes full trace objects with all steps (JSON) or a flat summary table (CSV).

Syntax

terminalCopy

bash

tracellm export [OPTIONS]

Option	Type	Default	Description
--format	str	json	Export format: json or csv
--limit	int	100	Number of recent traces to export (1–1000)

What Happens Internally

Validates format — raises an error if the format is not json or csv.
Fetches recent traces from MongoDB via fetch_recent_traces(limit).
Creates export directory — ./exports/ is created if it does not exist.
Generates a timestamp in the format YYYYMMDD-HHMMSS for the filename.
Writes the file:
- JSON — full trace objects with all steps, serialized with model_dump(mode="json")
- CSV — flat fields only: trace_id, project_id, prompt, model, status, latency, tokens, retries, timestamps, step count. Steps are not included.
Prints success message — shows the number of exported traces and the file path.

Example Output

Terminal outputCopy

text

  Exporting traces...

  ╭── Export Successful ─────────────────────────────────────╮
  │                                                          │
  │  12 traces exported                                      │
  │  File: exports/traces-20260531-142210.json               │
  │                                                          │
  ╰──────────────────────────────────────────────────────────╯

JSON Export Format

Each exported JSON file contains an array of trace objects. Each trace includes the full execution details:

exported-traces.jsonCopy

json

[
  {
    "trace_id": "tr_2kf9q3m1",
    "project_id": "default",
    "project_name": "default",
    "environment": "development",
    "prompt": "Explain transformers",
    "model_name": "gpt-4.1-mini",
    "status": "success",
    "latency": 3420.0,
    "token_count": 1247,
    "retry_count": 1,
    "slow_request": false,
    "failure_reason": null,
    "created_at": "2026-05-31T14:22:10",
    "updated_at": "2026-05-31T14:22:14",
    "steps": [
      {
        "tool_name": "query.embed",
        "duration": 180.0,
        "success": true,
        "input": {},
        "output": { "embedding": [...] }
      }
    ]
  }
]

CSV Export Format

The CSV format exports flat fields suitable for spreadsheet analysis. Steps are not included — only the step count per trace is recorded.

exported-traces.csvCopy

text

trace_id,project_id,project_name,environment,prompt,model_name,status,latency,token_count,retry_count,slow_request,failure_reason,created_at,updated_at,step_count
tr_2kf9q3m1,default,default,development,"Explain transformers",gpt-4.1-mini,success,3420.0,1247,1,false,,2026-05-31T14:22:10,2026-05-31T14:22:14,9
tr_4h8j2p5,default,default,development,"What is attention?",gpt-4.1-mini,success,1890.0,892,0,false,,2026-05-31T14:20:05,2026-05-31T14:20:08,7

Common Errors

Error	Cause	Fix
Invalid format	Format is not json or csv	Use --format json or --format csv
Export directory unwritable	Permissions issue with ./exports/	Check directory permissions or create it manually
No traces to export	MongoDB is empty	Run some traces first with tracellm trace

Troubleshooting

Tip

Export files are written to ./exports/ relative to the current working directory. Use absolute paths or run the command from your project root.