Agent và gateway

Collector agent và gateway là hai vai trò triển khai của cùng một OpenTelemetry Collector, không phải hai binary hoặc protocol khác nhau. Agent ở gần nguồn telemetry; gateway cung cấp một lớp ingest và policy dùng chung cho nhiều nguồn.

Mục lục

• Mental model agent và gateway
  • Agent
  • Gateway
  • Khi nào chọn topology nào
• Topology agent đến gateway
  • Kiến trúc tham chiếu
  • Luồng khi downstream bị chậm
• Phân chia trách nhiệm pipeline
  • Công việc nên đặt ở agent
  • Công việc nên đặt ở gateway
  • Routing khác load balancing
• Cấu hình tham khảo
  • Giả định và component cần có
  • Cấu hình agent và gateway
  • Routing theo policy tại gateway
  • Đọc data path của cấu hình
• Scaling và failure domains
  • Cô lập tầng agent
  • Scale pool gateway
  • Xử lý có trạng thái và scraper
• Security và trust boundaries
  • Bảo vệ từng network hop
  • Bảo vệ dữ liệu và credential
• Backpressure, durability và duplicate
  • Backpressure truyền qua các tầng
  • Sizing queue và retry
  • Vì sao telemetry có thể bị trùng
• Kiểm chứng end to end
  • Kiểm tra tĩnh
  • Gửi canary qua từng signal
  • Đối chiếu từng hop
  • Tiêm lỗi có kiểm soát
  • Kiểm tra routing và duplicate
• Rollout và rollback
  • Ghi baseline và ngưỡng dừng
  • Triển khai gateway trước
  • Chuyển một nhóm agent canary
  • Mở rộng và drain topology cũ
  • Rollback theo một thay đổi nguyên tử
• Checklist production
• Nguồn chính thức và bước tiếp theo

Mental model agent và gateway

Một Collector pipeline vẫn có dạng receiver → processors → exporters ở cả hai vai trò. Khác biệt nằm ở locality — Collector gần nguồn đến đâu — và failure domain — phạm vi workload bị ảnh hưởng khi Collector lỗi.

Agent

Agent chạy sát nơi dữ liệu được tạo. Sidecar đặt một agent trong mỗi pod nên cô lập tốt theo workload. DaemonSet thường đặt một agent trên mỗi Kubernetes node, phù hợp với file logs hoặc host metrics chỉ tồn tại tại node đó.

Agent không mặc nhiên đáng tin chỉ vì ở “nội bộ”. Một DaemonSet nhận traffic từ mọi pod trên node vẫn là ranh giới chia sẻ. Hãy giới hạn source, xác thực khi cần và không trộn tenant nếu threat model không cho phép.

Gateway

Gateway cung cấp một OTLP endpoint ổn định cho nhiều nguồn. Team platform có thể thay backend, rotate credential hoặc áp dụng policy mà không triển khai lại mọi ứng dụng.

“Tập trung” không có nghĩa là một Collector duy nhất. Một gateway production thường là pool nhiều replica. Pool cần load balancing, capacity, readiness, rolling upgrade và quan sát riêng cho từng exporter.

Khi nào chọn topology nào

Chọn agent đến gateway khi cả hai tầng đều có nhiệm vụ không thể bỏ. Nếu agent chỉ nhận OTLP rồi chuyển nguyên trạng và gateway không cung cấp policy hay failure boundary cần thiết, hop bổ sung chỉ làm tăng chi phí và điểm lỗi.

Topology agent đến gateway

Kiến trúc tham chiếu

Sơ đồ có ba network contract độc lập: ứng dụng đến agent, agent đến gateway và gateway đến backend. Với mỗi contract, ghi rõ endpoint, protocol, TLS mode, authentication, timeout, retry owner và giới hạn queue.

Luồng khi downstream bị chậm

Queue chỉ trì hoãn backpressure. Nếu tốc độ vào liên tục lớn hơn tốc độ ra, mọi queue hữu hạn cuối cùng đều đầy. Khi đó phải giảm volume, khôi phục hoặc tăng capacity downstream; tăng queue mãi chỉ dùng thêm memory hoặc disk.

Phân chia trách nhiệm pipeline

Công việc nên đặt ở agent

Đặt công việc tại agent khi nó cần context hoặc quyền chỉ có ở nguồn:

• nhận OTLP qua loopback, pod network hoặc node-local endpoint;
• đọc file log và checkpoint ngay nơi file tồn tại;
• thu host metrics một lần trên mỗi host;
• gắn metadata node, pod hoặc availability zone từ nguồn tin cậy;
• loại sớm telemetry dung lượng lớn mà policy chắc chắn không cần;
• batch và queue cho hop agent đến gateway trong outage budget đã định.

Đừng đặt tail sampling ở mọi agent nếu một trace đi qua nhiều node. Mỗi agent chỉ thấy một phần trace nên không thể ra quyết định toàn trace chính xác.

Công việc nên đặt ở gateway

Đặt công việc tại gateway khi cần policy và góc nhìn chung:

• xác thực nguồn và ánh xạ nguồn sang tenant đáng tin cậy;
• redact field trước khi dữ liệu rời trust boundary;
• route theo tenant, region, data class hoặc backend;
• fan-out có chủ đích trong migration;
• giữ credential và certificate client của backend;
• tail sample hoặc aggregate sau khi đã bảo đảm affinity;
• queue và retry cho hop egress đến backend.

Batch ở cả agent lẫn gateway là hợp lệ nhưng cộng dồn độ trễ. Ví dụ agent chờ 1s và gateway chờ 3s có thể thêm gần 4s trước network/backend latency trong trường hợp xấu. Hãy đặt latency budget end to end rồi tuning từng tầng.

Routing khác load balancing

Hai khái niệm thường bị nhầm:

• Routing connector đọc nội dung telemetry hoặc metadata request bằng OTTL (OpenTelemetry Transformation Language), rồi chuyển record sang pipeline đích. Ví dụ: tenant payments đi vào backend riêng.
• Load-balancing exporter phân phối telemetry giữa nhiều Collector downstream. Nó có thể hash theo trace ID hoặc service name để dữ liệu liên quan hội tụ về cùng instance.

Routing quyết định đường policy. Load balancing quyết định replica xử lý. Một L7 load balancer thông thường phù hợp với gateway stateless. Tail sampling hoặc aggregation theo service cần tầng load-balancing exporter có routing key phù hợp; round-robin tùy ý có thể chia nhỏ state.

Cấu hình tham khảo

Giả định và component cần có

Ví dụ dùng OTLP/gRPC giữa các tầng và ba signal traces, metrics, logs. Distribution phải chứa otlp, memory_limiter, batch, otlp_grpc, file_storage và health_check. Ví dụ routing còn cần connector routing, hiện có stability alpha cho ba signal trong các distribution được README liệt kê.

Trước khi sao chép cấu hình:

1. Thay endpoint, đường dẫn certificate và giới hạn tài nguyên bằng giá trị của môi trường.
2. Gắn volume bền vững nếu bật file_storage; một filesystem tạm không tạo durability qua reschedule.
3. Chỉ bind 127.0.0.1 khi sender thực sự dùng chung network namespace. Agent DaemonSet thường cần node-local address và network policy khác.
4. Kiểm tra field bằng README đúng tag release đã pin. Component alpha có thể đổi cấu hình hoặc behavior.

Cấu hình agent và gateway

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

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 75
    spike_limit_percentage: 15
  batch/agent:
    send_batch_size: 1024
    timeout: 1s

extensions:
  file_storage/agent:
    directory: /var/lib/otelcol/queue
    create_directory: true
  health_check:
    endpoint: 127.0.0.1:13133

exporters:
  otlp_grpc/gateway:
    endpoint: "${env:GATEWAY_OTLP_ENDPOINT}"
    timeout: 10s
    tls:
      ca_file: /var/run/secrets/otel/gateway-ca.crt
      cert_file: /var/run/secrets/otel/agent.crt
      key_file: /var/run/secrets/otel/agent.key
    sending_queue:
      enabled: true
      sizer: items
      queue_size: 20000
      num_consumers: 4
      storage: file_storage/agent
    retry_on_failure:
      enabled: true
      initial_interval: 1s
      max_interval: 30s
      max_elapsed_time: 10m

service:
  extensions: [file_storage/agent, health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch/agent]
      exporters: [otlp_grpc/gateway]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch/agent]
      exporters: [otlp_grpc/gateway]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch/agent]
      exporters: [otlp_grpc/gateway]

Routing theo policy tại gateway

Ví dụ đầy đủ dưới đây route traces của tenant payments tới backend riêng. Mọi trace không khớp đi vào pipeline hạn chế thay vì bị drop hoặc đi nhầm tenant. action: move ngăn record đã khớp tiếp tục được xét ở route sau.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        tls:
          cert_file: /var/run/secrets/otel/gateway.crt
          key_file: /var/run/secrets/otel/gateway.key
          client_ca_file: /var/run/secrets/otel/agent-ca.crt

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 75
    spike_limit_percentage: 15
  batch:
    send_batch_size: 4096
    timeout: 3s

connectors:
  routing/tenant:
    error_mode: ignore
    default_pipelines: [traces/restricted]
    table:
      - condition: 'resource.attributes["com.example.tenant.id"] == "payments"'
        action: move
        pipelines: [traces/payments]

exporters:
  otlp_grpc/payments:
    endpoint: "${env:PAYMENTS_OTLP_ENDPOINT}"
    headers:
      authorization: "${env:PAYMENTS_AUTHORIZATION}"
    tls:
      ca_file: /var/run/secrets/otel/payments-ca.crt
    sending_queue:
      enabled: true
      sizer: items
      queue_size: 50000
    retry_on_failure:
      enabled: true
      max_elapsed_time: 10m

  otlp_grpc/restricted:
    endpoint: "${env:RESTRICTED_OTLP_ENDPOINT}"
    headers:
      authorization: "${env:RESTRICTED_AUTHORIZATION}"
    tls:
      ca_file: /var/run/secrets/otel/restricted-ca.crt
    sending_queue:
      enabled: true
      sizer: items
      queue_size: 50000
    retry_on_failure:
      enabled: true
      max_elapsed_time: 10m

service:
  pipelines:
    traces/in:
      receivers: [otlp]
      processors: [memory_limiter]
      exporters: [routing/tenant]
    traces/payments:
      receivers: [routing/tenant]
      processors: [batch]
      exporters: [otlp_grpc/payments]
    traces/restricted:
      receivers: [routing/tenant]
      processors: [batch]
      exporters: [otlp_grpc/restricted]

com.example.tenant.id chỉ là namespace attribute minh họa. Không tin tenant ID do ứng dụng tùy ý gửi. Hãy suy ra tenant từ workload identity hoặc metadata đã được xác thực, sau đó ghi đè giá trị không đáng tin trước routing.

Routing connector chuyển dữ liệu giữa pipeline trong cùng process. Nó không tạo network queue, crash boundary hay quota riêng. Nếu tenant cần isolation mạnh, tách Collector process, workload identity, credential, storage và capacity.

Đọc data path của cấu hình

• Agent: otlp → memory_limiter → batch/agent → sending queue → otlp_grpc/gateway.
• Gateway cơ bản: otlp → memory_limiter → batch/gateway → sending queue → otlp_grpc/backend.
• Gateway có routing: otlp → memory_limiter → routing/tenant → traces/payments hoặc traces/restricted → batch → exporter queue → backend.

Processor chạy theo đúng thứ tự trong service.pipelines. Khai báo component ở khối cấp cao chưa làm nó hoạt động. Extension cũng phải xuất hiện trong service.extensions; ví dụ routing rút gọn dùng memory queue nên không khai báo file_storage.

Scaling và failure domains

Cô lập tầng agent

Sidecar và DaemonSet tạo failure domain khác nhau:

• Sidecar: một agent lỗi chủ yếu ảnh hưởng pod cùng nó. Đổi lại, tổng CPU, memory, connection và volume tăng theo số pod.
• DaemonSet: một agent phục vụ nhiều pod trên node. Nó hiệu quả cho host data, nhưng agent quá tải hoặc restart có thể làm mất đường thu của cả node.

Đặt request/limit và priority từ load test. Với DaemonSet, kiểm tra một workload ồn ào có làm refused_* tăng cho workload khác không. Nếu cần quota hoặc security isolation theo tenant, dùng agent hoặc pipeline riêng chưa đủ; cân nhắc tách process và node pool.

Scale pool gateway

Gateway stateless có thể scale ngang sau load balancer. Tuy vậy, gRPC thường giữ kết nối lâu. Một L4 load balancer có thể ghim nhiều request của client vào một replica. Dùng load balancer hiểu gRPC ở L7, hoặc kiểm tra client-side balancing và connection behavior bằng tải thật.

Theo dõi ít nhất:

• receiver accepted và refused theo signal;
• otelcol_processor_refused_* khi memory_limiter hoạt động;
• otelcol_exporter_queue_size so với otelcol_exporter_queue_capacity;
• enqueue failure, send failure và export latency theo exporter;
• CPU, RSS/heap, disk queue, restart và thời gian drain;
• latency và error rate của chính workload gửi telemetry.

Scale khi Collector là bottleneck. Nếu queue tăng vì backend hoặc network egress đã bão hòa, thêm gateway hay consumer có thể làm downstream tệ hơn. Nói ngắn gọn: xác định chặng chậm trước khi scale.

Phân tán replica qua node và availability zone phù hợp. Load balancer phải loại replica chưa ready, nhưng readiness chỉ chứng minh process nhận traffic; nó không chứng minh backend đang ingest.

Xử lý có trạng thái và scraper

Một số component không thể scale như receiver stateless:

• tail_sampling cần mọi span cùng trace đến cùng instance. Đặt tầng load-balancing exporter phía trước và hash theo trace ID.
• Aggregation theo service cần affinity theo service name nếu contract component yêu cầu.
• Prometheus receiver hoặc scraper khác cần chia target. Nhân bản cùng config có thể scrape trùng và vi phạm nguyên tắc single writer của metric stream.
• File log receiver cần ownership và checkpoint riêng; hai agent đọc cùng file có thể tạo duplicate.

Khi thay đổi số replica của tầng có state, kiểm tra rebalance, trace đang mở, checkpoint và duplicate. Một Deployment nhiều replica tự thân không giải quyết các contract này.

Security và trust boundaries

Bảo vệ từng network hop

• Bind receiver vào interface nhỏ nhất có thể. Loopback phù hợp cho sidecar cùng network namespace; gateway thường cần listener trên pod network.
• Dùng TLS cho agent đến gateway và gateway đến backend. Dùng mTLS khi gateway phải xác thực danh tính agent.
• Kiểm tra CA chain, SAN/hostname và thời hạn certificate. Không dùng insecure_skip_verify để chữa lỗi production.
• Giới hạn source bằng NetworkPolicy, firewall hoặc service mesh. Không expose OTLP receiver ra Internet nếu không có yêu cầu rõ ràng.
• Tách certificate, service account và quyền theo môi trường hoặc tenant. Thử trường hợp certificate hết hạn, sai CA và client không được cấp quyền.

mTLS xác thực certificate của client, nhưng authorization vẫn cần policy ánh xạ danh tính đó sang tenant và hành động được phép. Routing theo một resource attribute không thay thế authorization.

Bảo vệ dữ liệu và credential

• Giữ token backend tại gateway khi ứng dụng và agent không cần biết nó.
• Inject secret từ secret manager, file mount hoặc workload identity. Không commit token, private key hay effective config có secret.
• Redact Authorization header, cookie, query, email và PII trước khi dữ liệu rời trust boundary. Tốt nhất là không thu thập từ SDK ngay từ đầu.
• Queue trên disk chứa telemetry nguyên bản. Mã hóa volume, giới hạn quyền đọc và không đưa WAL vào support bundle hoặc backup thiếu kiểm soát.
• debug exporter có thể ghi payload nhạy cảm. Chỉ bật ngắn hạn trong môi trường hạn chế sau bước redaction.
• Giới hạn cardinality của metric attributes; tenant ID có kiểm soát có thể hợp lệ, nhưng user ID hoặc URL thô thường tạo quá nhiều time series.

Backpressure, durability và duplicate

Backpressure truyền qua các tầng

Backpressure là phản ứng khi downstream xử lý chậm hơn upstream. Trên data path đồng bộ, lỗi có thể truyền từ exporter về receiver. Sending queue chèn một ranh giới bất đồng bộ nhưng chỉ trong capacity đã cấp.

Với hai tầng Collector, cần viết rõ behavior tại cả hai hop:

1. Gateway retry backend trong bao lâu?
2. Khi queue gateway đầy, gateway trả lỗi hay drop theo contract component nào?
3. Agent có retry lỗi đó không và queue được bao lâu?
4. Khi agent đầy, SDK chờ, retry hay drop?
5. Việc chờ có ảnh hưởng latency hoặc tài nguyên ứng dụng không?

Không hứa “không mất dữ liệu” chỉ vì đã bật queue. Memory queue mất khi process chết. Persistent queue vẫn mất dữ liệu khi disk lỗi, đầy, volume biến mất hoặc retry hết hạn. Nếu cần replay dài hạn và delivery contract mạnh hơn, cân nhắc message broker bền vững giữa các tầng và chấp nhận chi phí vận hành bổ sung.

Sizing queue và retry

Ước lượng tối thiểu theo tải đo được:

số item cần giữ ≈ tốc độ item/giây × outage budget giây × hệ số an toàn

Ví dụ, 20.000 spans/giây trong outage budget 300 giây đã cần khoảng 6.000.000 spans, chưa gồm metrics, logs, batch overhead và spike. Nếu sending_queue.sizer là items, queue_size đo item chứ không đo byte. Hãy đo kích thước serialized và heap/disk thực thay vì chỉ dùng công thức.

Retry window phải phù hợp queue capacity. Queue chỉ giữ được hai phút nhưng retry mười lăm phút không tạo thêm mười ba phút durability. Sau backend phục hồi, tốc độ export còn phải lớn hơn tốc độ vào để drain backlog trong thời gian chấp nhận được.

Đặt alert trước khi queue đầy. Ngưỡng cụ thể phải đến từ load test và thời gian on-call cần để phản ứng. Quan sát cả queue ratio lẫn tốc độ thay đổi; queue ở 50% nhưng tăng nhanh có thể nguy hiểm hơn queue 70% đang drain.

Vì sao telemetry có thể bị trùng

Collector và OTLP không cung cấp exactly-once end to end. Duplicate có thể xuất hiện khi:

• backend đã nhận batch nhưng ACK bị mất; exporter timeout rồi gửi lại;
• agent và gateway đều retry cùng một sự cố;
• hai scraper cùng thu một target hoặc hai file receivers đọc cùng file;
• rollout cũ và mới cùng nhận một nguồn;
• fan-out gửi có chủ đích tới hai backend rồi hai luồng được nhập lại;
• routing dùng action: copy thay vì move;
• receiver hoặc exporter được tham chiếu ở nhiều pipeline tạo fan-out ngoài ý muốn;
• exporter quay lại receiver phía trước và tạo vòng lặp qua network.

Backend có thể deduplicate một số signal theo ID, nhưng không được giả định điều đó cho mọi backend. Với traces, so cùng trace_id và span_id. Với logs, thêm một canary event ID. Với metrics, giữ single writer và tìm out-of-order samples, jump hoặc rate tăng gấp đôi.

Kiểm chứng end to end

otelcol components
otelcol validate --config=file:/etc/otelcol/agent.yaml
otelcol validate --config=file:/etc/otelcol/gateway.yaml

telemetrygen traces --otlp-endpoint 127.0.0.1:4317 --otlp-insecure --service agent-gateway-canary --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

Rollout và rollback

Không nâng agent, gateway, routing policy và backend exporter trong cùng một đợt. Mỗi thay đổi độc lập giúp xác định đúng failure boundary khi canary lỗi.

Checklist production

• Mỗi signal có sơ đồ từ source đến backend, gồm receiver, processor, exporter, queue và owner.
• Mỗi agent/gateway có failure domain, request/limit, readiness và termination grace period rõ ràng.
• Gateway có nhiều replica và load balancing phù hợp với gRPC hoặc stateful processing.
• Scraper và metric stream giữ single writer; file receiver có ownership và checkpoint duy nhất.
• memory_limiter đứng sớm, batch gần cuối và tổng latency hai tầng nằm trong budget.
• Queue/retry được sizing từ ingress rate, outage budget, memory/disk và tốc độ drain đo được.
• TLS/mTLS, authorization, NetworkPolicy, secret rotation và redaction đã được test bằng cả trường hợp thất bại.
• Routing có default bảo thủ, fixture cho từng nhánh và không tin attribute tenant chưa xác thực.
• Có test backend outage, gateway outage, restart, queue overflow, lost ACK và duplicate.
• Rollout có canary, ngưỡng dừng, artifact rollback và thời gian drain trước khi tắt topology cũ.

Nguồn chính thức và bước tiếp theo

• Agent deployment pattern
• Gateway deployment pattern
• Scaling the Collector
• Collector resiliency
• Collector configuration
• Routing connector
• Load-balancing exporter