Ingest OTLP log records into Braintrust

Applies to:

Plan -
Deployment -

Summary

Braintrust-hosted organizations can send the OTel logs signal directly to /otel/v1/logs, which converts each log record into a span. Self-hosted deployments accept the traces signal only, so a source that emits log records needs a translation step until the logs endpoint reaches a data plane release.

What is happening

The OTLP intake exposes a signal-specific endpoint for each signal it accepts. Which endpoints your organization has depends on where its data plane runs:

Deployment	Traces	Logs
Braintrust-hosted, US (`https://api.braintrust.dev`)	`/otel/v1/traces`	`/otel/v1/logs`
Braintrust-hosted, EU (`https://api-eu.braintrust.dev`)	`/otel/v1/traces`	`/otel/v1/logs`
Self-hosted or custom data plane	`/otel/v1/traces`	Not available

For Collector or SDK configs that expect the base OTLP endpoint rather than a signal-specific one, use /otel and let the exporter append the signal path.

The logs endpoint is not in a released data plane version, so it is not available on self-hosted or custom data plane deployments. To confirm which endpoint your organization uses, check its API URL at Settings > Data plane. See Data plane region.

Fix or suggestion

Braintrust-hosted: send OTLP logs directly

Point the logs pipeline at your organization’s API URL. The endpoint accepts application/json and application/x-protobuf, and it authenticates with the same headers as the traces endpoint.

exporters:
  otlphttp/braintrust:
    endpoint: https://api.braintrust.dev/otel
    headers:
      Authorization: "Bearer ${BRAINTRUST_API_KEY}"
      x-bt-parent: "project_id:${BRAINTRUST_PROJECT_ID}"

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/braintrust]

Use https://api-eu.braintrust.dev/otel for EU-hosted organizations. Each log record becomes a span. A record that carries a trace ID joins that trace, parented under its span ID when the record has one. A record without a trace ID becomes its own root span. Braintrust maps GenAI semantic-convention attributes onto span fields, and records the record’s body along with its severity number and severity text. The .NET SDK sends this signal for you. Its BRAINTRUST_LOGS_PATH variable defaults to /otel/v1/logs, so no configuration is needed on a hosted organization. See the C# API reference.

Self-hosted: send spans instead of log records

Because the logs endpoint is not available on a self-hosted deployment, translate log records into spans and send those. If your adapter can emit real OTLP spans, forward them to the traces endpoint. This is the least work to maintain:

exporters:
  otlphttp/braintrust:
    endpoint: https://your-braintrust-instance.example.com/otel
    headers:
      Authorization: "Bearer ${BRAINTRUST_API_KEY}"
      x-bt-parent: "project_id:${BRAINTRUST_PROJECT_ID}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/braintrust]

If it cannot emit spans, use a small adapter service that writes rows through the insert API:

Read OTLP log records from the source.
Group related records by a stable ID, such as session.id or prompt.id.
Create one synthetic root span per group.
Convert each log record into a child span.
Insert the translated spans with POST /v1/project_logs/{project_id}/insert.

Example span mapping:

Source field	Braintrust field
`session.id`	`root_span_id`, `metadata.session_id`
`prompt.id`	`metadata.prompt_id`
`model`	`metadata.model`
`cost_usd`	`metrics.estimated_cost`
`input_tokens`	`metrics.prompt_tokens`
`output_tokens`	`metrics.completion_tokens`
`total_tokens`	`metrics.tokens`
`prompt`	`input`
event name	`span_attributes.name`, `metadata.event_type`

Minimal insert example:

curl -X POST https://your-braintrust-instance.example.com/v1/project_logs/{project_id}/insert \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "id": "<root-row-uuid>",
        "root_span_id": "<session.id>",
        "span_id": "<session.id>",
        "span_parents": [],
        "metadata": { "session_id": "<session.id>" },
        "span_attributes": { "type": "task", "name": "claude_cowork_session" }
      },
      {
        "id": "<child-row-uuid>",
        "root_span_id": "<session.id>",
        "span_id": "<event-uuid>",
        "span_parents": ["<session.id>"],
        "input": "<prompt text>",
        "metadata": {
          "model": "claude-3-5-sonnet",
          "event_type": "api_request",
          "session_id": "<session.id>"
        },
        "metrics": {
          "prompt_tokens": 512,
          "estimated_cost": 0.0014
        },
        "span_attributes": { "type": "llm", "name": "api_request" }
      }
    ]
  }'

The standard OTel Collector transform processor can modify log attributes, but it does not by itself promote log records into trace spans. For production log-to-span translation, use a small adapter service or a custom Collector connector that creates real spans.

How to confirm it worked

Open Logs and confirm spans appear for the records you sent.
If you send OTLP logs directly, confirm that records carrying a trace ID appear inside that trace rather than as separate root spans.
If you translate records into spans, confirm one trace appears per grouped session.id or prompt.id, and that the synthetic root span contains session metadata.
Confirm token and cost fields appear under metrics.
If the response reports rejected log records, check that each record has a resolvable parent. A 403 means the API key cannot write to the project named in x-bt-parent.

​Summary

​What is happening

​Fix or suggestion

​Braintrust-hosted: send OTLP logs directly

​Self-hosted: send spans instead of log records

​How to confirm it worked

Summary

What is happening

Fix or suggestion

Braintrust-hosted: send OTLP logs directly

Self-hosted: send spans instead of log records

How to confirm it worked