OTLP/gRPC và OTLP/HTTP

OTLP/gRPC và OTLP/HTTP mang cùng data model OTLP nhưng dùng cách đóng gói request khác nhau. Trang này giúp chọn transport, cấu hình hai đầu khớp nhau và chẩn đoán lỗi ở ranh giới mạng. Nếu chưa quen ExportRequest, Resource hoặc batch, hãy đọc OTLP trước; trang hiện tại vẫn tóm tắt đủ để dùng độc lập.

Mục lục

• Ranh giới giữa protocol và transport
  • Giống nhau và khác nhau ở đâu?
  • Mental model của một Export call
• So sánh OTLP/gRPC và OTLP/HTTP
• Endpoint, port và path theo signal
  • Port mặc định
  • Endpoint chung và endpoint theo signal
  • Base path phía sau reverse proxy
• Cấu hình OTLP/gRPC
  • SDK gửi qua gRPC bằng biến môi trường
  • Collector export bằng gRPC
• Cấu hình OTLP/HTTP
  • SDK gửi qua HTTP bằng biến môi trường
  • Collector export bằng HTTP
• Headers, compression và TLS
  • Authentication headers
  • Compression
  • TLS và mTLS
• Status, retry và backpressure
  • gRPC status
  • HTTP status
  • Partial success và duplicate
• Kiểm chứng transport
  • Kiểm tra OTLP/HTTP bằng curl
  • Kiểm tra OTLP/gRPC bằng grpcurl
  • Gửi canary có dữ liệu thật
• Lỗi thường gặp
• Checklist chọn transport
• Nguồn chính thức và bài liên quan

Ranh giới giữa protocol và transport

OTLP định nghĩa Protobuf schema, Export request/response và hành vi khi lỗi. Transport quyết định request đó đi trên gRPC hay HTTP. Hình sau giữ bốn lớp tách biệt:

Giống nhau và khác nhau ở đâu?

Cả hai transport dùng các message như ExportTraceServiceRequest và ExportTraceServiceResponse. Chúng cũng cùng có full success, partial success, lỗi retryable và lỗi permanent.

Điểm khác là lớp mạng:

• OTLP/gRPC gọi unary RPC Export trên service Protobuf của từng signal.
• OTLP/HTTP dùng POST tới URL path của từng signal.
• OTLP/gRPC dùng Protobuf nhị phân bên trong gRPC wire format.
• OTLP/HTTP có thể dùng Protobuf nhị phân hoặc Protobuf JSON mapping.
• gRPC thường dùng HTTP/2. OTLP/HTTP có thể dùng HTTP/1.1 hoặc HTTP/2.

Unary RPC là một lần client gửi một request và nhận một response, thay vì mở stream records vô hạn. Client vẫn có thể chạy nhiều unary requests đồng thời để tăng throughput.

Mental model của một Export call

records của một signal
  → tạo Export<Signal>ServiceRequest
  → serialize
  → thêm metadata/headers, compression và TLS
  → gửi qua gRPC method hoặc HTTP path
  → đọc transport status + Export<Signal>ServiceResponse

Transport thành công chưa đủ. Client còn phải đọc partial_success trong response. Ngược lại, một lỗi transport chỉ nên retry khi OTLP phân loại lỗi đó là tạm thời.

So sánh OTLP/gRPC và OTLP/HTTP

Không có transport thắng trong mọi hệ thống. gRPC thường phù hợp cho service-to-service nơi HTTP/2 được hỗ trợ tốt. HTTP/Protobuf thường phù hợp khi firewall, proxy hoặc platform serverless đã tối ưu cho HTTP request thông thường. Đo latency, CPU, bandwidth và failure behavior trên topology thật trước khi đổi transport chỉ vì benchmark tổng quát.

Endpoint, port và path theo signal

Port mặc định

4317 và 4318 là default, không phải luật bắt buộc. Backend managed thường dùng 443, còn reverse proxy có thể dùng host/path riêng. Luôn lấy endpoint từ backend contract thay vì tự thay port theo thói quen.

Collector OTLP receiver hiện mặc định bind localhost, không phải mọi interface. Ví dụ production nên ghi endpoint tường minh để tránh hành vi thay đổi theo version hoặc network namespace.

Endpoint chung và endpoint theo signal

Với OTLP/HTTP, hai loại biến endpoint có semantics khác nhau:

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

Exporter dùng endpoint chung làm base URL và tạo:

http://collector:4318/v1/traces
http://collector:4318/v1/metrics
http://collector:4318/v1/logs

Nhưng endpoint theo signal được dùng nguyên trạng:

export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4318/v1/traces

Cấu hình sai thường gặp sau gửi traces tới path /, không phải /v1/traces:

# Sai nếu receiver chỉ expose path mặc định /v1/traces
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4318

Với OTLP/gRPC, cả endpoint chung và endpoint theo signal đều là gRPC target. Không thêm /v1/traces, /v1/metrics hoặc /v1/logs; method Protobuf đã chọn signal.

Base path phía sau reverse proxy

Endpoint chung OTLP/HTTP có thể chứa base path. Dùng dấu / cuối để intent rõ ràng:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.example.com/otel/
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

URL hiệu lực là:

https://telemetry.example.com/otel/v1/traces
https://telemetry.example.com/otel/v1/metrics
https://telemetry.example.com/otel/v1/logs

Reverse proxy phải giữ POST, body, Content-Type, Content-Encoding và auth headers. Nó cũng phải route đúng base path tới OTLP receiver. Test từng signal vì một rule chỉ match /v1/traces có thể âm thầm bỏ metrics và logs.

Cấu hình OTLP/gRPC

SDK gửi qua gRPC bằng biến môi trường

Mẫu sau gửi cả ba signal qua gRPC có TLS tới gateway. Scheme https yêu cầu kết nối secure và có precedence trên tùy chọn INSECURE:

export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-gateway.example.com:4317
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=${OTEL_API_KEY}"
export OTEL_EXPORTER_OTLP_CERTIFICATE=/var/run/secrets/otel/ca.pem
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_TIMEOUT=10000

OTEL_EXPORTER_OTLP_TIMEOUT dùng milliseconds và áp dụng cho mỗi batch export. Mặc định chuẩn là 10000 ms. Mức hỗ trợ env vars vẫn phụ thuộc SDK; kiểm tra environment variable compliance matrix.

Cho local plaintext, dùng scheme http tường minh:

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317

Một số gRPC API programmatic dùng target host:port và cờ insecure riêng. Đừng sao chép hình dạng endpoint của một ngôn ngữ sang ngôn ngữ khác mà không đọc API của SDK đó.

Collector export bằng gRPC

Mẫu gateway nhận OTLP/gRPC ở loopback, batch rồi gửi tới backend bằng TLS và header. Các giá trị ${env:...} được Collector lấy từ environment process:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 127.0.0.1:4317

processors:
  batch:
    timeout: 5s

exporters:
  otlp_grpc/backend:
    endpoint: "${env:OTLP_GRPC_BACKEND}"
    headers:
      authorization: "Bearer ${env:OTLP_TOKEN}"
    compression: gzip
    timeout: 10s
    tls:
      ca_file: /var/run/secrets/otel/ca.pem
    sending_queue:
      enabled: true
      queue_size: 1000
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 5m

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc/backend]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc/backend]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc/backend]

Chạy validation với secret giả và endpoint staging hợp lệ:

export OTLP_GRPC_BACKEND=backend.example.com:4317
export OTLP_TOKEN=redacted-for-validation
otelcol validate --config=file:./otelcol-grpc.yaml

Ví dụ dùng tên component hiện hành otlp_grpc. Các Collector cũ có thể dùng tên otlp; OTLP/HTTP cũ thường dùng otlphttp. Hãy pin distribution và đối chiếu tài liệu đúng version. Không đổi component name chỉ dựa vào một snippet mới.

Cấu hình OTLP/HTTP

SDK gửi qua HTTP bằng biến môi trường

Endpoint chung dưới đây tự thêm path cho traces, metrics và logs:

export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-gateway.example.com/otel/
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=${OTEL_API_KEY}"
export OTEL_EXPORTER_OTLP_CERTIFICATE=/var/run/secrets/otel/ca.pem
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_TIMEOUT=10000

Nếu backend tách endpoint theo signal, ghi URL đầy đủ:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://traces.example.com/v1/traces
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://metrics.example.com/v1/metrics
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.example.com/v1/logs

Option theo signal ghi đè option chung cùng loại. Đừng giả định headers chung và headers theo signal được merge; nếu đặt biến theo signal, hãy cấu hình đầy đủ headers cần thiết cho signal đó.

Collector export bằng HTTP

Mẫu này nhận local OTLP/HTTP và gửi tiếp tới base URL backend. otlp_http exporter tự thêm path mặc định theo signal:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318

processors:
  batch:
    timeout: 5s

exporters:
  otlp_http/backend:
    endpoint: "${env:OTLP_HTTP_BACKEND}"
    headers:
      x-api-key: "${env:OTLP_API_KEY}"
    encoding: proto
    compression: gzip
    timeout: 10s
    tls:
      ca_file: /var/run/secrets/otel/ca.pem
    sending_queue:
      enabled: true
      queue_size: 1000
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 5m

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/backend]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/backend]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/backend]

export OTLP_HTTP_BACKEND=https://backend.example.com/otel/
export OTLP_API_KEY=redacted-for-validation
otelcol validate --config=file:./otelcol-http.yaml

encoding: proto tạo Content-Type: application/x-protobuf. Chỉ đổi thành json khi backend công bố hỗ trợ OTLP JSON mapping. Tên otlphttp là alias đã bị deprecate trên Collector hiện hành; dùng tên đúng với version đã pin.

Headers, compression và TLS

Authentication headers

OTLP không áp đặt một scheme authentication duy nhất. Backend có thể yêu cầu Authorization, x-api-key hoặc header tenant riêng. Với SDK env vars, format chuẩn là danh sách key=value phân cách bằng dấu phẩy:

export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=${OTEL_API_KEY},x-tenant=shop"

Format này theo W3C Baggage. Dấu phẩy, dấu bằng, khoảng trắng và ký tự không hợp lệ trong key/value phải được percent-encode theo format đó. Dấu chấm phẩy không phải delimiter được hỗ trợ. Kiểm tra SDK cụ thể vì parser và diagnostics có thể khác nhau.

Với Collector, headers là YAML mapping nên giá trị có khoảng trắng có thể viết trực tiếp:

headers:
  authorization: "Bearer ${env:OTLP_TOKEN}"
  x-tenant: shop

Header phía exporter chỉ gắn metadata lên request outbound. Nó không tự bảo vệ Collector receiver. Để xác thực inbound, cấu hình authenticator extension mà distribution hỗ trợ, hoặc đặt Collector sau một proxy/gateway xác thực. Kết hợp với network policy và rate limit; chỉ kiểm tra header tĩnh không chống được credential bị lộ.

Compression

Mọi OTLP server phải hỗ trợ none và gzip theo specification. Với OTLP/HTTP, request gzip mang header Content-Encoding: gzip. Với gRPC, compression nằm trong cơ chế gRPC.

export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

Gzip giảm bandwidth nhưng dùng thêm CPU và request vẫn phải được kiểm tra giới hạn kích thước sau giải nén. Đừng dùng compression để che batch quá lớn. Benchmark với payload thật: spans ít attributes có thể tiết kiệm ít hơn logs nhiều text lặp.

Specification không ép client dùng gzip làm default. Collector exporters hiện hành có thể bật gzip mặc định, nhưng đó là hành vi implementation/version. Đặt gzip hoặc none tường minh nếu kết quả vận hành cần ổn định qua upgrade.

TLS và mTLS

TLS mã hóa kết nối và xác minh server. mTLS (mutual TLS) còn yêu cầu client trình certificate để server xác minh hai chiều.

SDK dùng endpoint https và các file sau:

Ví dụ mTLS ở SDK:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-gateway.example.com:4317
export OTEL_EXPORTER_OTLP_CERTIFICATE=/var/run/secrets/otel/ca.pem
export OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE=/var/run/secrets/otel/client.pem
export OTEL_EXPORTER_OTLP_CLIENT_KEY=/var/run/secrets/otel/client-key.pem

Collector exporter là TLS client:

tls:
  ca_file: /var/run/secrets/otel/ca.pem
  cert_file: /var/run/secrets/otel/client.pem
  key_file: /var/run/secrets/otel/client-key.pem

Collector receiver là TLS server; client_ca_file bật yêu cầu xác minh client certificate:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        tls:
          cert_file: /var/run/secrets/otel/server.pem
          key_file: /var/run/secrets/otel/server-key.pem
          client_ca_file: /var/run/secrets/otel/client-ca.pem
      http:
        endpoint: 0.0.0.0:4318
        tls:
          cert_file: /var/run/secrets/otel/server.pem
          key_file: /var/run/secrets/otel/server-key.pem
          client_ca_file: /var/run/secrets/otel/client-ca.pem

Certificate server phải có SAN khớp hostname client dùng. insecure: true tắt TLS hoàn toàn; insecure_skip_verify: true vẫn mã hóa nhưng bỏ xác minh server. Không dùng hai tùy chọn này để chữa lỗi certificate trong production. Sửa CA, SAN, clock hoặc certificate chain.

Status, retry và backpressure

Backpressure là tín hiệu server yêu cầu client giảm tốc vì không theo kịp. Client phải giới hạn queue và retry; nếu giữ vô hạn, outage downstream sẽ biến thành lỗi memory ở application hoặc Collector.

gRPC status

OTLP/gRPC dùng gRPC status code. Các nhóm quan trọng:

Server quá tải nên trả UNAVAILABLE và có thể kèm RetryInfo.retry_delay. Client vẫn cần exponential backoff với jitter nếu không có chỉ dẫn cụ thể.

HTTP status

OTLP/HTTP chỉ định bốn status lỗi phải retry:

Một vài permanent errors thường gặp:

• 400 Bad Request: body không decode được hoặc dữ liệu không hợp lệ.
• 401/403: thiếu credential, token sai hoặc thiếu quyền.
• 404: route/path sai.
• 413 Content Too Large: body sau giải nén vượt limit.

Nếu server ngắt kết nối mà không trả response, hoặc client không kết nối được, client nên retry với exponential backoff và jitter. Kết nối HTTP nên được keep-alive giữa các requests.

Partial success và duplicate

Full success của OTLP/HTTP là 200 OK với Export<Signal>ServiceResponse. Với partial success, status vẫn là 200 OK, nhưng response có rejected count và error_message. gRPC tương tự: RPC thành công nhưng response có partial_success. Client không retry request partial success.

Nếu kết nối mất trước response, client có thể gửi lại request mà server đã nhận. Điều này tạo duplicate. OTLP ưu tiên khả năng giao nhận hơn exactly-once trong trường hợp mơ hồ đó. Backend và truy vấn nên chịu được duplicate ở mức hợp lý, còn operator phải theo dõi reconnect/retry storm.

Kiểm chứng transport

Kiểm tra OTLP/HTTP bằng curl

Một Protobuf message rỗng mã hóa thành body rỗng. OTLP server nên trả success cho empty request. Vì vậy, lệnh sau kiểm tra DNS, route, TLS/auth và decoder cơ bản:

curl --fail-with-body --verbose \
  --request POST \
  --header 'Content-Type: application/x-protobuf' \
  --data-binary '' \
  http://127.0.0.1:4318/v1/traces

Kỳ vọng HTTP/1.1 200 hoặc HTTP/2 200 và Content-Type: application/x-protobuf. Response full success rỗng có thể có body 0 byte vì Protobuf không cần mã hóa field nào.

Với TLS và API key:

curl --fail-with-body --verbose \
  --cacert /var/run/secrets/otel/ca.pem \
  --header "x-api-key: ${OTEL_API_KEY}" \
  --header 'Content-Type: application/x-protobuf' \
  --data-binary '' \
  https://otel-gateway.example.com/v1/traces

Kiểm tra OTLP/gRPC bằng grpcurl

Collector OTLP receiver không bắt buộc bật server reflection. Vì vậy, cung cấp file .proto từ repository opentelemetry-proto thay vì dựa vào lệnh list:

grpcurl -plaintext \
  -import-path ./opentelemetry-proto \
  -proto opentelemetry/proto/collector/trace/v1/trace_service.proto \
  -d '{}' \
  127.0.0.1:4317 \
  opentelemetry.proto.collector.trace.v1.TraceService/Export

Với TLS, thay -plaintext bằng -cacert /path/to/ca.pem. Thêm metadata bằng -H 'x-api-key: redacted' khi cần. Lệnh gửi empty ExportTraceServiceRequest; response {} cho biết service/method hoạt động, không chứng minh backend đã ingest span.

Gửi canary có dữ liệu thật

Dùng application đã instrument hoặc telemetrygen để tạo đúng records. Ví dụ gRPC local:

telemetrygen traces --otlp-endpoint 127.0.0.1:4317 --otlp-insecure --traces 1
telemetrygen metrics --otlp-endpoint 127.0.0.1:4317 --otlp-insecure --metrics 1
telemetrygen logs --otlp-endpoint 127.0.0.1:4317 --otlp-insecure --logs 1

Sau đó:

1. Xác nhận Collector receiver nhận từng signal bằng telemetry nội bộ hoặc debug exporter tạm thời.
2. Kiểm tra exporter không có retry, auth hoặc TLS error.
3. Query backend theo service.name, trace ID hoặc tên metric/log canary.
4. Kiểm tra response partial success và rejected counters.
5. Gỡ tool/debug output khỏi production path sau khi hoàn tất.

Để so sánh transport công bằng, giữ nguyên records, batch size, compression, network path và backend. Chỉ đổi transport; nếu đổi đồng thời queue hay TLS, kết quả benchmark không còn trả lời transport nào tạo khác biệt.

Lỗi thường gặp

Checklist chọn transport

Chọn OTLP/gRPC khi phần lớn câu trả lời là “có”:

• SDK và backend hỗ trợ gRPC ổn định cho mọi signal cần dùng.
• Mọi proxy/load balancer trên đường đi hỗ trợ HTTP/2 và gRPC upstream.
• Team có tool và dashboard để đọc gRPC status/metadata.
• Kết nối service-to-service dài hạn hưởng lợi từ gRPC client đã được tối ưu.
• Network policy không chặn hoặc downgrade HTTP/2.

Chọn OTLP/HTTP với Protobuf khi phần lớn câu trả lời là “có”:

• Platform/proxy hỗ trợ HTTP request thông thường tốt hơn gRPC.
• Cần route theo path/host bằng hạ tầng HTTP hiện có.
• Serverless, edge hoặc egress policy làm gRPC khó vận hành.
• Team cần probe status/header/route bằng công cụ HTTP phổ biến.
• Backend công bố OTLP/HTTP là đường ingest được ưu tiên hoặc duy nhất.

Bất kể transport nào, chỉ đưa vào production khi:

• Protocol, endpoint hiệu lực, port và path đã được ghi rõ.
• TLS xác minh hostname; mTLS/auth headers được quản lý bằng secret runtime.
• Compression, timeout, queue và retry có giới hạn.
• Canary của traces, metrics và logs đều xuất hiện ở backend.
• Partial success, rejected data, queue saturation và retry được quan sát.
• Failure test đã bao phủ 401/403, throttling, timeout và backend outage.

Nếu hai lựa chọn đều đáp ứng, ưu tiên transport đã được platform và backend hỗ trợ tốt nhất. Sau đó benchmark trên payload thật. Khả năng vận hành khi lỗi quan trọng hơn chênh lệch nhỏ trong microbenchmark.

Nguồn chính thức và bài liên quan

Các endpoint, path, content type, status, compression, TLS và retry trong trang dựa trên:

• OTLP Specification
• OTLP Exporter Specification
• OTLP Exporter Configuration
• Collector OTLP receiver
• Collector OTLP gRPC exporter
• Collector OTLP HTTP exporter
• Collector TLS configuration