Skip to main content
Sentrial can ingest OpenTelemetry traces over OTLP HTTP JSON. Each trace becomes a Sentrial session, and each span becomes an event in the session timeline.
The current endpoint accepts OTLP HTTP JSON. OTLP protobuf is not enabled yet. If you use the OpenTelemetry Collector, set encoding: json.

​
When to Use OTel

Use this integration when:
  • your agent framework already emits OpenTelemetry spans
  • you have an existing OpenTelemetry Collector
  • you want vendor-neutral tracing alongside Sentrial classification
  • you are migrating gradually from another tracing tool
For new Sentrial-first integrations, use the native SDK instead.

Native SDK

Best for rich Sentrial sessions, prompt variants, costs, and wrappers.

Ingestion Options

Compare the native SDK and OpenTelemetry paths.

​
Endpoint

POST https://api.sentrial.com/api/otel/v1/traces
Authenticate with either header: 
Authorization: Bearer sentrial_live_xxx
x-sentrial-api-key: sentrial_live_xxx
Your API key needs both sessions:write and events:write scopes.

​
Collector Configuration

Forward traces from an OpenTelemetry Collector to Sentrial: 
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  batch:
    timeout: 1s
    send_batch_size: 100
    send_batch_max_size: 1000
  resource:
    attributes:
      - key: service.name
        value: my-agent
        action: upsert

exporters:
  otlphttp/sentrial:
    traces_endpoint: https://api.sentrial.com/api/otel/v1/traces
    encoding: json
    headers:
      x-sentrial-api-key: ${env:SENTRIAL_API_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch, resource]
      exporters: [otlphttp/sentrial]
For local development with the API server on port 3001, use: 
exporters:
  otlphttp/sentrial:
    traces_endpoint: http://localhost:3001/api/otel/v1/traces
    encoding: json
    headers:
      x-sentrial-api-key: ${env:SENTRIAL_API_KEY}
Add these attributes to the root span when possible:
AttributePurpose
sentrial.agent.nameAgent name in Sentrial
sentrial.user_id or user.idUser grouping
sentrial.convo_id or conversation.idConversation grouping
sentrial.inputSession input
sentrial.outputSession output
sentrial.costEstimated run cost
sentrial.experiment.assignment_idLinks the trace to a prompt variant assignment
Sentrial also maps common GenAI semantic convention attributes, including:
  • gen_ai.system
  • gen_ai.request.model
  • gen_ai.usage.input_tokens
  • gen_ai.usage.output_tokens
  • gen_ai.usage.total_tokens
  • gen_ai.prompt
  • gen_ai.completion

​
Minimal OTLP JSON Example

curl -X POST https://api.sentrial.com/api/otel/v1/traces \
  -H "Content-Type: application/json" \
  -H "x-sentrial-api-key: sentrial_live_xxx" \
  -d '{
    "resourceSpans": [
      {
        "resource": {
          "attributes": [
            { "key": "service.name", "value": { "stringValue": "support-agent" } }
          ]
        },
        "scopeSpans": [
          {
            "spans": [
              {
                "traceId": "4fd0b6131f2f4ad9b4d05cc182b1fb11",
                "spanId": "9f3c4e3b8d9a1001",
                "name": "support request",
                "kind": "SPAN_KIND_SERVER",
                "startTimeUnixNano": "1770000000000000000",
                "endTimeUnixNano": "1770000002500000000",
                "attributes": [
                  { "key": "sentrial.agent.name", "value": { "stringValue": "support-agent" } },
                  { "key": "sentrial.user_id", "value": { "stringValue": "user_123" } },
                  { "key": "sentrial.convo_id", "value": { "stringValue": "conv_789" } },
                  { "key": "sentrial.input", "value": { "stringValue": "Help me reset my password" } },
                  { "key": "sentrial.output", "value": { "stringValue": "I sent a reset link." } },
                  { "key": "gen_ai.usage.input_tokens", "value": { "intValue": 1200 } },
                  { "key": "gen_ai.usage.output_tokens", "value": { "intValue": 300 } }
                ],
                "status": { "code": "STATUS_CODE_OK" }
              }
            ]
          }
        ]
      }
    ]
  }'

​
Prompt Variants with OTel

OpenTelemetry ingestion does not choose prompt variants by itself. Route the variant first, then attach the assignment ID to your trace. 
import { sentrial } from '@sentrial/sdk';

sentrial.configure({ apiKey: process.env.SENTRIAL_API_KEY! });

const assignment = await sentrial.getVariant({
  experimentName: 'support-prompt-v2',
  agentName: 'support-agent',
  userId: user.id,
  convoId: conversation.id,
});

const systemPrompt = assignment.systemPrompt ?? defaultSystemPrompt;
Add assignment.assignmentId to your root span as sentrial.experiment.assignment_id. Sentrial will link the ingested trace to that variant and classify the run after ingest.

​
Classification

After Sentrial ingests a trace, it marks the session complete, stores span events, and runs the same signal classification pipeline used for SDK-created sessions.

​
Next Steps

Sessions

Learn how sessions and events appear in Sentrial.

Custom Integration

Track custom agents with the native SDK.