การเชื่อมต่อ OpenTelemetry

ส่งออก Trace การค้นคืนไปยังระบบตรวจสอบของคุณผ่าน OTLP

01ภาพรวม 60 วินาที

Seizn ส่งออก OpenTelemetry Trace แบบ Native สำหรับทุกการค้นคืน เชื่อมต่อกับแบ็กเอนด์ที่รองรับ OTLP ใดก็ได้สำหรับการตรวจสอบแบบครบวงจร

✓ส่งออก OTLP แบบไม่ต้องตั้งค่าพร้อมสร้าง Span อัตโนมัติ
✓Attribute ที่ครบถ้วน ได้แก่ เวลาตอบสนอง จำนวนโทเค็น และต้นทุน
✓Context Propagation สำหรับ Distributed Tracing

แบ็กเอนด์ที่รองรับ

DatadogGrafana TempoJaegerHoneycombNew RelicZipkin

02การตั้งค่า

กำหนดค่าการส่งออก OTLP ผ่านตัวแปรสภาพแวดล้อม

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"

03ตัวอย่างแบ็กเอนด์

Datadog

ส่งออก Trace ไปยัง Datadog APM ผ่าน Datadog Agent หรือ 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

ส่ง Trace ไปยัง Grafana Tempo (Cloud หรือ 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

ส่งออกไปยัง Jaeger พร้อมรองรับ 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

04เคล็ดลับสำหรับ Production

กลยุทธ์ Sampling

ควบคุมปริมาณ Trace ด้วย Head-based หรือ 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 Attribute

เพิ่ม Resource และ Span Attribute เพื่อการกรองที่ดีขึ้น

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

ปรับประสิทธิภาพการส่งออกด้วยการตั้งค่า Batch

typescript

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

05การแก้ไขปัญหา

ปัญหา	สาเหตุ	วิธีแก้ไข
ไม่มี Trace ปรากฏ	Telemetry ปิดอยู่หรือ Endpoint ไม่ถูกต้อง	ตั้งค่า SEIZN_TELEMETRY_ENABLED=true และตรวจสอบ Endpoint
การเชื่อมต่อถูกปฏิเสธ	Collector ไม่ทำงานหรือพอร์ตไม่ถูกต้อง	ตรวจสอบสถานะ Collector และพอร์ต 4318
Span หายไปใน Trace	อัตรา Sampling ต่ำเกินไป	เพิ่มอัตรา Sampling หรือปิด Sampling

โหมด Debug

เปิดใช้งาน Debug Logging เพื่อแก้ไขปัญหา Telemetry

bash

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

การเชื่อมต่อ LlamaIndex กลับไปยังการเชื่อมต่อ