OpenTelemetry

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}

Recommended Attributes

Add these attributes to the root span when possible:

Attribute	Purpose
`sentrial.agent.name`	Agent name in Sentrial
`sentrial.user_id` or `user.id`	User grouping
`sentrial.convo_id` or `conversation.id`	Conversation grouping
`sentrial.input`	Session input
`sentrial.output`	Session output
`sentrial.cost`	Estimated run cost
`sentrial.experiment.assignment_id`	Links 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.

When to Use OTel

Native SDK

Ingestion Options

Endpoint

Collector Configuration

Recommended Attributes

Minimal OTLP JSON Example

Prompt Variants with OTel

Classification

Next Steps

Sessions

Custom Integration

​When to Use OTel

Native SDK

Ingestion Options

​Endpoint

​Collector Configuration

​Recommended Attributes

​Minimal OTLP JSON Example

​Prompt Variants with OTel

​Classification

​Next Steps

Sessions

Custom Integration

When to Use OTel

Endpoint

Collector Configuration

Recommended Attributes

Minimal OTLP JSON Example

Prompt Variants with OTel

Classification

Next Steps