> ## Documentation Index
> Fetch the complete documentation index at: https://learn.kubit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload traces to a Sandbox workspace

> Export traces from OpenTelemetry, Langfuse, Phoenix, MLflow, LangSmith, Braintrust, Datadog, AgentCore or Cortex and upload the file to a Kubit Sandbox workspace, with no change to your app.

A Sandbox workspace takes trace files you export from another tool and upload by hand. It has no ingestion pipeline and no API key, so your app and its instrumentation stay as they are. At the end, your traces are in **Activity** and labelled by the Evaluator. Use it for a proof of concept. To send live traces later, follow the [Quickstart](https://learn.kubit.ai/agent-observability/get-started/quickstart.md) in a new Agent workspace.

## Before you start

* [ ] Traces in one of the tools under [Export from your tool](#export-from-your-tool), and access to export them
* [ ] A Kubit account that can create workspaces, in an organization with **Sandbox** turned on. See [Set up your organization](https://learn.kubit.ai/start-here/admin.md).
* [ ] For the commands below: `jq` 1.7 or later, and the tool's own CLI where a section names one

## Prompt for your coding agent

Paste this into Claude Code, Cursor or Codex, with your tool in place of `<tool>`. It writes the file and leaves credentials and the upload to you:

```text theme={null}
Read https://learn.kubit.ai/agent-observability/integrate/sandbox-upload.md.
Export my traces from <tool> as in that tool's section under "Export from your tool".
I'll set any API keys or tokens myself. Don't print them or ask me for them.
Write one uncompressed .jsonl file under 300 MB and tell me how many records it has.
```

## Steps

### 1. Export your traces

Export the traces to one file with the commands for your tool under [Export from your tool](#export-from-your-tool). Kubit reads the format from the file, so keep the records as the tool writes them.

| **Constraint** | **Value** |
| - | - |
| **File size** | Up to 300 MB (300,000,000 bytes) |
| **File types** | `.jsonl`, `.ndjson` or `.json`, uncompressed UTF-8. Gzip, zip, bz2, xz and zstd files are refused. |
| **Record size** | Up to 4 MB per line or array element. Save one record per line. |
| **Labelling** | The Evaluator skips a trace with more than 500 spans or over 4 MB |

### 2. Create a Sandbox workspace

In Kubit, open the workspace menu at the top left and click **New workspace**. Enter a **Workspace Name**, set **Origin** to **Sandbox** and click **Continue**.

![Create Workspace dialog with Workspace Name Logfire POC, Workspace Timezone Europe/Paris (UTC+1\*) and Origin Sandbox, with the hint that it uploads OTel trace files for quick testing with no pipeline, above the Continue button.](https://mintcdn.com/kubit/nip5DDQ8d0G82bAs/images/agent-observability/cookbook/logfire/create-sandbox-workspace.png?fit=max\&auto=format\&n=nip5DDQ8d0G82bAs\&q=85\&s=6c0906d90c8d284ed84ba7859eb15cac)

If **Sandbox** isn't in the **Origin** list, your organization doesn't have it turned on. Ask [support@kubit.co](mailto:support@kubit.co) to turn it on. Kubit creates the workspace and opens **Modeler** on the **Uploads** tab.

### 3. Upload the file

Drag the file onto **Drop a trace file here**, or click **browse** and pick it. In a workspace that already has uploads, click **Add data** first. Then click **Upload & preview** and keep the browser tab open until the upload reads `Uploaded. Ready to review.`

![The Uploads section of the Modeler with an Add data button. The drop zone reads Drop a trace file here or browse, JSONL or JSON up to 300 MB, from OTLP, Langfuse, Phoenix, MLflow, LangSmith, Braintrust, Datadog, AgentCore or Cortex. Below it are MLflow traces in your warehouse? with a Copy from a table button, and a collapsed How to export spans section.](https://mintcdn.com/kubit/BtadhRbx_tTjeUxn/images/agent-observability/sandbox/upload-drop-zone.png?fit=max\&auto=format\&n=BtadhRbx_tTjeUxn\&q=85\&s=a4790e1983152166860f63339cca17d5)

> [!WARNING]
>
> Your first upload sets the workspace's destination to the Kubit-managed warehouse. It stays that way even if you discard the file, and you can't switch the workspace to another connection.

### 4. Check the preview

Kubit reads a sample from the start of the file and shows a preview. Check these:

| **Part of the preview** | **What to check** |
| - | - |
| **Format** | Reads your tool with `(detected)`, such as **Langfuse (detected)**. If it's wrong, pick the right one. The format can't change once the import starts. |
| **Records sampled** and **Accepted spans** | Equal, or close. A gap means some records didn't match the format. |
| **Labels in this file** | Shows only when the file carries labels or scores. Keep **Use these labels and scores** checked to use them. Labelled traces skip the Evaluator. |
| **Proposed initial model** | The model the import creates. You don't need to change it. |

If the preview says `The records match more than one format. Each is read as its own unless you choose one.`, pick your tool under **Format**.

### 5. Import the spans

Under **After import**, pick what labels the traces:

| **Option** | **What happens** |
| - | - |
| **Run the Evaluator** | The Evaluator starts labelling the traces as soon as the import succeeds |
| **I'll upload labels** | Nothing labels the traces until you apply a labels file or start the Evaluator. Traces with uploaded labels are never relabelled by the Evaluator. |

Tick **I reviewed the sample and the data model.** and click **Import spans**. The import runs through **Checking the file**, **Reading spans**, **Saving to the warehouse** and **Preparing reports**. You can leave the page while it runs.

When it's done, the upload reads **Succeeded**, with these counts:

![An upload named logfire.otel.jsonl marked Succeeded, 55.6 MB, Format: OpenTelemetry (OTLP), with tiles reading Spans imported 5,334, Duplicates 0, Skipped 0 and Time range Oct 30, 2026.](https://mintcdn.com/kubit/BtadhRbx_tTjeUxn/images/agent-observability/sandbox/import-summary.png?fit=max\&auto=format\&n=BtadhRbx_tTjeUxn\&q=85\&s=cd3fa32ee6a2d0b798f73b549641d610)

**Duplicates** counts spans already in the workspace, matched on trace ID and span ID. They aren't imported again, so you can upload overlapping exports.

**Constraint:** Kubit keeps an uploaded file for 24 hours. If you don't import it by then, upload it again.

### 6. Add a labels file (optional)

To use labels or scores you already have instead of the Evaluator's, click **Add labels file** in the upload's **Labelling** section. Drop the file on **Drop a labels file here**, click **Upload labels file**, review it and click **Apply labels**. Each tool's section below says where its labels come from.

A label names what happened, such as `tool_error`. A score from 0 to 1 answers an enabled Evaluator question, such as `resolved`. A pass, fail, yes or no is named after its check, as in `relevance_fail`. True adds `<name>`, false adds `<name>_false`.

> [!WARNING]
>
> A labels file replaces the labels on every trace it names. Put all of a trace's labels in one file.

### 7. Open the traces

Open **Activity**, keep **Subject** on **Trace** and click **Execute**. **Time Range** counts back from the last day in your data, shown as **Reports through**, so older exports still show up. Click a trace to see its spans, and **Labels** once the Evaluator has labelled it.

## Export from your tool

Each section has the export the **How to export spans** section in the app shows for that tool. The upload drop zone lists the same tools by their short names.

### OpenTelemetry (OTLP)

Save spans as OTLP JSON: one envelope or span per line, or a JSON array. The OpenTelemetry Collector's file exporter writes this. Kubit skips a line over 4 MB. To split an envelope into single spans:

```bash Split OTLP envelopes into spans theme={null}
jq -c '.resourceSpans[] as $r | $r.scopeSpans[] as $s | $s.spans[] + {resource: $r.resource, scope: $s.scope}' spans.json > spans.jsonl
```

Each span needs `traceId`, `spanId`, `startTimeUnixNano` and `endTimeUnixNano`, with camelCase keys and hex IDs. Attributes must be typed, as in `{"key": "gen_ai.tool.name", "value": {"stringValue": "search_orders"}}`. Kubit maps the OpenTelemetry GenAI attributes (`gen_ai.*`). Labels and scores come from `gen_ai.evaluation.result` span events. For Pydantic Logfire, see [Logfire traces in a Sandbox](https://learn.kubit.ai/agent-observability/cookbook/logfire-sandbox.md).

### Langfuse

Kubit reads no labels from Langfuse trace files. Add them with a labels file of Langfuse scores.

Export **Enriched observations** to blob storage as JSONL, with **Gzip Compression** off, then join the files. Legacy observations have no session, user or tags.

```bash Join Langfuse observation exports theme={null}
cat observations_v2/*.jsonl > observations.jsonl
```

Or call the API, adding `cursor=<meta.cursor>` until none comes back, and join the pages. Times are ISO 8601, such as `2026-10-01T00:00:00Z`.

```text Langfuse observations API theme={null}
GET /api/public/v2/observations?fields=core,basic,io,metadata,model,usage,trace_context&fromStartTime=<from>&toStartTime=<to>&limit=1000
```

```bash Join the API pages theme={null}
jq -c '.data[]' page*.json > observations.jsonl
```

Each record needs `id`, `trace_id`, `type`, `start_time` and `end_time`. For labels, export scores to blob storage the same way (`cat scores/*.jsonl > scores.jsonl`), download them from the **Scores** page as JSON, or call `GET /api/public/v3/scores?fields=details,subject&limit=100`. Boolean and categorical scores become labels, numeric scores answer an enabled Evaluator question, and text and correction scores are ignored.

### Arize Phoenix

Select rows in a project's **Spans** or **Traces** table, click the download icon, set **Data** to **Traces** and pick **JSONL**. OTLP JSON works too, up to the 4 MB record limit. Each record needs `context.trace_id`, `context.span_id`, `span_kind`, `start_time`, `end_time` and `status_code`. Annotations in the file are read as labels.

### MLflow

In Python with MLflow 3.5 or later, write each trace as one line of a `.jsonl` file. A trace over 4 MB can't be read. On Databricks with Unity Catalog storage, first set `MLFLOW_TRACING_SQL_WAREHOUSE_ID` to a SQL warehouse ID.

```python export_mlflow_traces.py theme={null}
import mlflow
with open("traces.jsonl", "w") as f:
    for t in mlflow.search_traces(locations=["<experiment_id>"], return_type="list"):
        f.write(t.to_json() + "\n")
```

Assessments in each trace are read as labels and scores. If the traces are already in a Snowflake, Databricks or BigQuery table, click **Copy from a table** under **MLflow traces in your warehouse?** instead of uploading a file. The table needs `trace_id`, `request_time`, and `spans` or `assessments`, and it's copied once.

### LangSmith

Kubit reads no labels from LangSmith trace files, because a run carries only feedback totals. Add labels with a labels file of LangSmith feedback.

Export with the LangSmith CLI, then join the files. The CLI keeps at most 1,000 runs per trace.

```bash Export LangSmith runs theme={null}
langsmith trace export <dir> --project <name> --full --limit <N> --since <date>
cat <dir>/*.jsonl > runs.jsonl
```

Or `POST /api/v2/runs/query` and join the pages with `jq -c '.items[]' *.json > runs.jsonl`. Without `min_start_time`, only the last 24 hours come back. Each run needs `trace_id`, `id`, `run_type`, `start_time` and `end_time`. For labels, save the project's feedback from `GET /api/v1/feedback?session=<project id>&limit=100&offset=<N>`, one record per line.

### Braintrust

Delete any old `bt-sync` folder, then pull the logs with the `bt` CLI and join the part files. Without `--traces`, it takes 100 traces.

```bash Export Braintrust logs theme={null}
bt sync pull project_logs:<project> --window 24h --traces <N>
cat bt-sync/project_logs_*/*/data/part-*.jsonl > spans.jsonl
```

Each span needs `root_span_id`, `span_id`, `metrics.start` and `metrics.end`. Scores and classifications in the file are read as scores and labels.

### Datadog LLM Observability

Call the export API with `DD-API-KEY` and `DD-APPLICATION-KEY` (with curl, add `-g`). Save each page as `page1.json`, `page2.json` and so on, asking for the next with `page[cursor]=<meta.page.after>` until it's missing. Without a range, it returns the last 15 minutes.

```text Datadog spans export API theme={null}
GET https://api.<site>/api/v2/llm-obs/v1/spans/events?filter[from]=<time>&filter[to]=<time>&page[limit]=5000
```

```bash Join the pages theme={null}
jq -c '.data[].attributes' page*.json > spans.jsonl
```

Each span needs `trace_id`, `span_id`, `span_kind`, `start_ns` and `duration`. Each span's `evaluation` is read as labels and scores.

### AWS Bedrock AgentCore

Kubit reads no labels from AgentCore trace files. Add them with a labels file of evaluation results.

Save the agent's spans log stream as it is, then split it if it's over 4 MB:

```bash Export AgentCore spans theme={null}
aws logs filter-log-events --log-group-name /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name> --log-stream-names spans --output json > spans.json
jq -c '.events[].message | fromjson?' spans.json > spans.jsonl
```

For an agent created before Jul 20, 2026, on ADOT older than 0.18.0, or with `UNIFIED_TRACES_DESTINATION_ENABLED=false`, read `aws/spans` too, with `--log-group-name aws/spans --log-stream-names default --start-time <ms> --end-time <ms>`. That group holds no prompts or replies. For labels, read the evaluation results group, by default `/aws/bedrock-agentcore/evaluations/results/<config id>`.

### Snowflake Cortex

In SnowSQL or the Snowflake CLI, not a worksheet, unload the agent's events to one JSONL file and download it. `<dir>` is a full path, such as `/Users/me/Downloads`.

```sql Unload Cortex Agent events theme={null}
ALTER SESSION SET TIMESTAMP_NTZ_OUTPUT_FORMAT = 'YYYY-MM-DD"T"HH24:MI:SS.FF9';
COPY INTO @~/kubit/cortex-events.jsonl
  FROM (SELECT OBJECT_CONSTRUCT(*) FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
    '<database>', '<schema>', '<agent>', 'CORTEX AGENT')))
  FILE_FORMAT = (TYPE = JSON COMPRESSION = NONE)
  SINGLE = TRUE MAX_FILE_SIZE = 300000000 OVERWRITE = TRUE;
GET @~/kubit/cortex-events.jsonl file://<dir>/;
```

Use a role with `MONITOR` on the agent, or `USAGE` on an External Agent, and the `SNOWFLAKE.CORTEX_USER` database role. Without `READ UNREDACTED AI OBSERVABILITY EVENTS TABLE`, prompts and replies come out redacted. For a TruLens app, use `'EXTERNAL AGENT'`. Evaluations in the events are read as scores. Thumbs feedback isn't read yet.

## Verify

The upload worked when all three are true:

* The upload in **Modeler** > **Uploads** reads **Succeeded**, and **Spans imported** plus **Duplicates** and **Skipped** add up to the spans you exported.
* **Activity** lists your traces, with the span names you know from your tool.
* After the Evaluator runs, **Labels** shows labels instead of `Not analysed yet`.

## If it fails

| **Symptom** | **Cause** | **Fix** |
| - | - | - |
| `Choose a non-empty file no larger than 300 MB (300,000,000 bytes).` | The file is empty or over 300 MB | Export a shorter time range |
| `Choose uncompressed UTF-8 JSONL or JSON.` | The file is compressed | Unzip it, or export with compression off |
| `A record is over 4 MB. Save one record per line.` | A line or array element holds more than one record, or one very large record | Split the file into one record per line, such as with the `jq` command for your tool |
| `Doesn't match the chosen format.` | The records don't match the format picked under **Format** | Pick your tool under **Format**, or export again as that tool's section shows |
| **Accepted spans** is well below **Records sampled** | OTLP attributes are flat key-value pairs, or IDs aren't hex | Export typed OTLP attributes, as the Collector's file exporter writes them |
| `Another import is processing in this workspace.` | A workspace runs one import at a time | Wait for the other import to finish, then try again |
| The upload can't be imported any more | The file was uploaded more than 24 hours ago | Upload it again |
| **Labels** reads `Not analysed yet` | The Evaluator hasn't labelled the trace yet | Wait for the run in the upload's **Labelling** section to finish, then click **Refresh** in **Activity** |

## Next Steps

* [Logfire traces in a Sandbox](https://learn.kubit.ai/agent-observability/cookbook/logfire-sandbox.md): the whole flow worked through on a Pydantic Logfire project.
* [Add your own eval questions](https://learn.kubit.ai/agent-observability/use/eval-questions.md): ask your own questions of every uploaded conversation.
* [Quickstart](https://learn.kubit.ai/agent-observability/get-started/quickstart.md): send live traces to an Agent workspace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.