# Gửi qua OpenTelemetry Collector

> Cấu hình Collector chuẩn nhận OTLP gRPC/HTTP từ app và chuyển tới Belvador qua otlphttp, có giới hạn bộ nhớ, batch, hàng đợi và gửi lại.

[OpenTelemetry Collector](https://opentelemetry.io/docs/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:

```yaml title="collector.yaml"
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
      http:
        endpoint: localhost:4318

processors:
  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: true

service:
  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

```bash
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á:

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf   # hoặc grpc với cổng 4317
export OTEL_SERVICE_NAME=my-service
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production
export 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.