📊Official

OpenTelemetry Integration

Export retrieval traces to your observability stack via OTLP.

0160-Second Overview

Seizn natively exports OpenTelemetry traces for every retrieval operation. Connect to any OTLP-compatible backend for end-to-end observability.

✓Zero-config OTLP export with automatic span creation
✓Rich attributes including latency, token counts, and costs
✓Context propagation for distributed tracing

Supported Backends

DatadogGrafana TempoJaegerHoneycombNew RelicZipkin

02Setup

Configure OTLP export via environment variables.

Environment Variablesbash

# Enable OTLP export in your Seizn client
# Set these environment variables

# Required: OTLP endpoint
export SEIZN_OTLP_ENDPOINT="https://your-collector:4318"

# Optional: Authentication
export SEIZN_OTLP_HEADERS="Authorization=Bearer your-token"

# Optional: Service name (default: seizn-client)
export SEIZN_SERVICE_NAME="my-rag-app"

03Backend Examples

Datadog

Export traces to Datadog APM via the Datadog Agent or direct API.

Datadog Configurationbash

# Option 1: Direct to Datadog (via Agent)
export SEIZN_OTLP_ENDPOINT="http://localhost:4318"
# Datadog Agent must have OTLP receiver enabled

# Option 2: Direct to Datadog API
export SEIZN_OTLP_ENDPOINT="https://trace.agent.datadoghq.com"
export SEIZN_OTLP_HEADERS="DD-API-KEY=your-datadog-api-key"

# Enable in Seizn
export SEIZN_TELEMETRY_ENABLED="true"

datadog-agent.yamlyaml

otlp_config:
  receiver:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

Grafana Tempo

Send traces to Grafana Tempo (Cloud or self-hosted).

Grafana Cloud Configurationbash

# Grafana Cloud
export SEIZN_OTLP_ENDPOINT="https://tempo-us-central1.grafana.net/tempo"
export SEIZN_OTLP_HEADERS="Authorization=Basic $(echo -n 'instance-id:api-token' | base64)"

# Self-hosted Tempo
export SEIZN_OTLP_ENDPOINT="http://tempo:4318"

# Enable in Seizn
export SEIZN_TELEMETRY_ENABLED="true"

Jaeger

Export to Jaeger with native OTLP receiver support.

Jaeger Configurationbash

# Jaeger with OTLP receiver (v1.35+)
export SEIZN_OTLP_ENDPOINT="http://jaeger:4318"
export SEIZN_TELEMETRY_ENABLED="true"

Docker Compose Examplebash

# Run Jaeger with OTLP support
docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest

04Production Tips

Sampling Strategy

Control trace volume with head-based or tail-based sampling.

typescript

import { Seizn } from 'seizn';

const client = new Seizn({
  apiKey: process.env.SEIZN_API_KEY,
  telemetry: {
    enabled: true,
    samplingRate: 0.1, // Sample 10% of traces
    // Or use tail-based sampling
    sampleOnlyErrors: true,
    sampleSlowRequests: {
      enabled: true,
      thresholdMs: 1000,
    },
  },
});

Custom Attributes

Add resource and span attributes for better filtering.

typescript

const client = new Seizn({
  apiKey: process.env.SEIZN_API_KEY,
  telemetry: {
    enabled: true,
    resourceAttributes: {
      'deployment.environment': 'production',
      'service.version': '1.2.3',
      'service.namespace': 'rag-apps',
    },
    spanAttributes: {
      'user.tier': 'enterprise',
      'feature.flag.rerank': 'enabled',
    },
  },
});

Batch Configuration

Optimize export performance with batch settings.

typescript

const client = new Seizn({
  apiKey: process.env.SEIZN_API_KEY,
  telemetry: {
    enabled: true,
    batchConfig: {
      maxQueueSize: 2048,
      scheduledDelayMs: 5000,
      maxExportBatchSize: 512,
    },
  },
});

05Troubleshooting

Issue	Cause	Solution
No traces appearing	Telemetry disabled or endpoint wrong	Set SEIZN_TELEMETRY_ENABLED=true and verify endpoint
Connection refused	Collector not running or wrong port	Check collector status and port 4318
Missing spans in trace	Sampling rate too low	Increase sampling rate or disable sampling

Debug Mode

Enable debug logging to troubleshoot telemetry issues.

bash

export SEIZN_TELEMETRY_DEBUG="true"
export OTEL_LOG_LEVEL="debug"

LlamaIndex Integration Back to Integrations