📊Chính thức

Tích hợp OpenTelemetry

Xuất trace truy xuất đến hệ thống quan sát của bạn qua OTLP.

01Tổng quan 60 giây

Seizn xuất trace OpenTelemetry một cách native cho mọi thao tác truy xuất. Kết nối với bất kỳ backend tương thích OTLP nào để quan sát end-to-end.

✓Xuất OTLP không cần cấu hình với tạo span tự động
✓Thuộc tính phong phú bao gồm độ trễ, số token và chi phí
✓Context propagation cho distributed tracing

Backend được hỗ trợ

DatadogGrafana TempoJaegerHoneycombNew RelicZipkin

02Thiết lập

Cấu hình xuất OTLP qua biến môi trường.

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"

03Ví dụ Backend

Datadog

Xuất trace đến Datadog APM qua Datadog Agent hoặc API trực tiếp.

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

Gửi trace đến Grafana Tempo (Cloud hoặc 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

Xuất đến Jaeger với hỗ trợ 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

04Mẹo cho Production

Chiến lược Sampling

Kiểm soát lượng trace với sampling head-based hoặc 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,
    },
  },
});

Thuộc tính tùy chỉnh

Thêm thuộc tính resource và span để lọc tốt hơn.

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

Cấu hình Batch

Tối ưu hiệu suất xuất với cài đặt batch.

typescript

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

05Xử lý sự cố

Vấn đề	Nguyên nhân	Giải pháp
Không có trace xuất hiện	Telemetry bị tắt hoặc endpoint sai	Đặt SEIZN_TELEMETRY_ENABLED=true và xác minh endpoint
Kết nối bị từ chối	Collector không chạy hoặc sai port	Kiểm tra trạng thái collector và port 4318
Thiếu span trong trace	Tỷ lệ sampling quá thấp	Tăng tỷ lệ sampling hoặc tắt sampling

Chế độ Debug

Bật debug logging để xử lý sự cố telemetry.

bash

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

Tích hợp LlamaIndex Quay lại tích hợp