Gửi qua OpenTelemetry Collector

OpenTelemetry Collector là một tiến trình chuẩn nhận telemetry từ các app rồi chuyển tiếp. Hãy dùng nó khi exporter chỉ nói gRPC, khi exporter của runtime không gửi lại, khi bạn muốn một chỗ duy nhất giữ khoá Belvador, hoặc với ngôn ngữ Belvador chưa tự chạy thử.

Đã kiểm ngày 2026-10-27 với otelcol-contrib 0.163.1, telemetrygen v0.163.0: traces đạt, logs đạt, metrics đạt.

Cấu hình#

Dùng bản contrib (otelcol-contrib). Cấu hình này chỉ dùng thành phần chuẩn:

receivers:  otlp:    protocols:      grpc:        endpoint: localhost:4317      http:        endpoint: localhost:4318processors:  memory_limiter:    check_interval: 1s    limit_percentage: 80    spike_limit_percentage: 20  batch: {}exporters:  otlphttp/belvador:    endpoint: ${env:BELVADOR_OTLP_ENDPOINT}    headers:      Authorization: Bearer ${env:BELVADOR_INGEST_KEY}    compression: gzip    retry_on_failure:      enabled: true    sending_queue:      enabled: trueservice:  pipelines:    traces:      receivers: [otlp]      processors: [memory_limiter, batch]      exporters: [otlphttp/belvador]    logs:      receivers: [otlp]      processors: [memory_limiter, batch]      exporters: [otlphttp/belvador]    metrics:      receivers: [otlp]      processors: [memory_limiter, batch]      exporters: [otlphttp/belvador]

• Receivers nhận OTLP qua gRPC (4317) và HTTP (4318) từ app. Chúng nghe ở localhost; trong container, dùng 0.0.0.0:4317 và 0.0.0.0:4318 để container khác gọi được, và đừng mở các cổng đó ra internet.

• memory_limiter từ chối dữ liệu mới trước khi Collector hết bộ nhớ, để exporter của app lùi lại thay vì Collector bị sập.

• batch gom bản ghi thành ít request hơn, lớn hơn (vẫn dưới giới hạn 4 MiB mỗi request).

• otlphttp/belvador gửi tới Belvador có nén gzip; retry_on_failure gửi lại khi gặp 429, 502, 503 và 504 với thời gian chờ tăng dần, còn sending_queue giữ dữ liệu trong bộ nhớ trong lúc đó.

Chạy#

export BELVADOR_OTLP_ENDPOINT=https://ingest.belvador.dev/otlp/<project-id>export BELVADOR_INGEST_KEY=<your-ingest-key>otelcol-contrib --config collector.yaml

Với Docker, dùng image otel/opentelemetry-collector-contrib, gắn cùng file đó vào /etc/otelcol-contrib/config.yaml và truyền hai biến bằng -e.

Cho app gửi tới Collector#

App gửi tới Collector, không cần khoá:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf   # hoặc grpc với cổng 4317export OTEL_SERVICE_NAME=my-serviceexport OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=productionexport OTEL_METRICS_EXPORTER=none   # otlp để gửi cả metrics (khoá có Metrics)

Mỗi app giữ OTEL_SERVICE_NAME và môi trường riêng; Collector chuyển nguyên các thuộc tính resource.

Khi Collector khởi động lại#

Hàng đợi ở trên nằm trong bộ nhớ: nếu Collector khởi động lại trong lúc không gọi được Belvador, dữ liệu đang chờ bị mất. Muốn giữ trên đĩa, thêm extension file_storage của bản contrib và trỏ sending_queue.storage vào nó. Lần chạy của Belvador không bao gồm cách cài này.

File log#

App chỉ ghi ra file log có thể được receiver filelog của bản contrib đọc và gửi qua cùng pipeline logs. Bản ghi đọc từ file không mang trace ID trừ khi dòng log có sẵn và bạn tách nó ra; receiver này không nằm trong phần đã kiểm.