OpenTelemetry

Sentrial can ingest OpenTelemetry traces over OTLP HTTP (JSON or protobuf, optionally gzipped). Each trace becomes a Sentrial session, and each span becomes an event in the session timeline.

The endpoint accepts both OTLP HTTP JSON and OTLP HTTP protobuf (application/x-protobuf). If you use the OpenTelemetry Collector, encoding: json still works but is no longer required — the default protobuf encoding is accepted too.

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. The canonical collector config lives at services/otel-collector/config.yaml in the repo — keep this snippet in sync with it:

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
  # No resource processor: your SDK already sets service.name on the OTLP resource,
  # so the collector should not overwrite it. Add one back only if you deliberately
  # want to force a single service name onto every trace.

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]
      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

Sentrial reads standard OpenTelemetry GenAI semantic-convention attributes — no Sentrial-specific attributes are required. Instrument with plain OTel and you are a first-class citizen. The one attribute Sentrial depends on is the conversation id (gen_ai.conversation.id) — a standard GenAI semconv attribute that older or base OTel tooling may not emit by default, so you may need to set it explicitly to group multi-turn sessions.

Purpose	Standard attribute (recommended)
Conversation group	`gen_ai.conversation.id` ← the one attribute Sentrial depends on
Agent / service	`service.name` (resource) or `agent.name`
User grouping	`user.id` or `enduser.id`
Model	`gen_ai.request.model`
Input / prompt	`gen_ai.prompt` or `gen_ai.input.messages`
Output / completion	`gen_ai.completion` or `gen_ai.output.messages`
Tokens	`gen_ai.usage.input_tokens` / `output_tokens` / `total_tokens`
Cost	`gen_ai.usage.cost`
Tool name	`gen_ai.tool.name` or `tool.name`

Conversation grouping is the one attribute Sentrial depends on that you may need to set explicitly. Set the standard gen_ai.conversation.id on your spans to group multi-turn runs into one conversation; conversation.id (unprefixed) is accepted as an alias.

Legacy attributes (deprecated)

Earlier integrations used sentrial.* attributes (sentrial.agent.name, sentrial.user_id, sentrial.convo_id, sentrial.input, sentrial.output, sentrial.cost, sentrial.tool.name) and ad-hoc conversation keys (convo.id, thread.id, chat.id, session.conversation_id). These are still read as lower-priority fallbacks for backward compatibility, but are deprecated — prefer the standard attributes above. (sentrial.experiment.assignment_id remains specific to production prompt A/B testing.)

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": "gen_ai.conversation.id", "value": { "stringValue": "conv_789" } },
                  { "key": "user.id", "value": { "stringValue": "user_123" } },
                  { "key": "gen_ai.prompt", "value": { "stringValue": "Help me reset my password" } },
                  { "key": "gen_ai.completion", "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.

Getting Started

Core Concepts

SDKs

Integrations

API Reference

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