Integrasi OpenTelemetry

Ekspor trace pengambilan ke stack observabilitas Anda melalui OTLP.

01Ikhtisar 60 Detik

Seizn secara native mengekspor trace OpenTelemetry untuk setiap operasi pengambilan. Hubungkan ke backend yang kompatibel dengan OTLP untuk observabilitas end-to-end.

✓Ekspor OTLP tanpa konfigurasi dengan pembuatan span otomatis
✓Atribut kaya termasuk latensi, jumlah token, dan biaya
✓Context propagation untuk distributed tracing

Backend yang Didukung

DatadogGrafana TempoJaegerHoneycombNew RelicZipkin

02Pengaturan

Konfigurasi ekspor OTLP melalui variabel lingkungan.

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"

03Contoh Backend

Datadog

Ekspor trace ke Datadog APM melalui Datadog Agent atau API langsung.

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

Kirim trace ke Grafana Tempo (Cloud atau 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

Ekspor ke Jaeger dengan dukungan OTLP receiver native.

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

04Tips Produksi

Strategi Sampling

Kontrol volume trace dengan sampling head-based atau tail-based.

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,
    },
  },
});

Atribut Kustom

Tambahkan atribut resource dan span untuk penyaringan yang lebih baik.

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',
    },
  },
});

Konfigurasi Batch

Optimalkan performa ekspor dengan pengaturan batch.

typescript

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

05Pemecahan Masalah

Masalah	Penyebab	Solusi
Tidak ada trace yang muncul	Telemetri dinonaktifkan atau endpoint salah	Atur SEIZN_TELEMETRY_ENABLED=true dan verifikasi endpoint
Koneksi ditolak	Collector tidak berjalan atau port salah	Periksa status collector dan port 4318
Span hilang dalam trace	Tingkat sampling terlalu rendah	Naikkan tingkat sampling atau nonaktifkan sampling

Mode Debug

Aktifkan debug logging untuk memecahkan masalah telemetri.

bash

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

Integrasi LlamaIndex Kembali ke Integrasi