Belajar OpenTelemetry - OTLP Protocol & Export ke Backend

#Pendahuluan

Sepanjang series ini kalian terus melihat kata OTLP — tetapi belum pernah kita buka isinya. Episode 8 menutup Fase 2 dengan membedah protokol yang menjadi bahasa pengiriman telemetry: OTLP (OpenTelemetry Protocol). Ini adalah lapisan yang memastikan data sampai utuh, terkompresi, dan bisa diterima oleh backend mana pun.

Mengapa penting? Karena saat data "hilang" atau exporter mengeluarkan error, hampir selalu melibatkan OTLP: salah port, salah protokol, kompresi tidak didukung backend, atau retry yang tidak dikonfigurasi. Memahami protokol ini mengubah debugging dari menebak-nebak menjadi pemeriksaan sistematis.

#OTLP dalam Satu Paragraf

OTLP adalah protokol encoding protobuf yang mendefinisikan struktur data untuk traces, metrics, dan logs. Ia memisahkan model data (seperti TracesData yang berisi ResourceSpans → ScopeSpans → Span) dari transport (gRPC atau HTTP). Versi stabil saat ini adalah OTLP v1.10.0 (9 Maret 2026).

Karena ketiga sinyal memakai satu protokol, satu pipeline tunggal bisa membawa semuanya — inilah yang membuat arsitektur episode 17 (korelasi tiga pilar) menjadi sederhana.

#Transport: gRPC vs HTTP

OTLP didefinisikan di dua jalur transport dengan port default yang berbeda:

Keduanya membawa payload protobuf yang sama. OTLP/HTTP juga mendukung JSON encoding (dengan header Content-Type: application/json) — sangat berguna untuk debug manual.

#Uji OTLP/HTTP dengan JSON

Kirim satu trace sederhana via curl untuk membuktikan pipeline hidup:

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSpans": [
      {
        "resource": {
          "attributes": [
            {"key": "service.name", "value": {"stringValue": "curl-test"}}
          ]
        },
        "scopeSpans": [
          {
            "spans": [
              {
                "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
                "spanId": "00f067aa0ba902b7",
                "name": "manual-span",
                "kind": 2,
                "startTimeUnixNano": "1690000000000000000",
                "endTimeUnixNano": "1690000000500000000"
              }
            ]
          }
        ]
      }
    ]
  }'

Jika collector merespons 200 dan span muncul di Jaeger, protokol dan pipeline kalian sudah benar. Inilah teknik debug tercepat yang jarang dipakai.

#Kompresi: gRPC dan HTTP

Telemetry dalam volume besar sangat hemat bila dikompresi. OTLP mendukung gzip pada kedua transport:

OTEL_EXPORTER_OTLP_COMPRESSION=gzip

Aturan praktisnya: aktifkan kompresi di lingkungan ber-bandwidth terbatas (VPS, edge, kantor cabang). Di jaringan lokal data center, kompresi menambah CPU dengan keuntungan kecil. Collector juga melakukan kompresi sendiri saat meneruskan ke backend berikutnya (episode 14).

#Konfigurasi Exporter SDK

Semua konfigurasi exporter OTLP bisa dilakukan lewat environment variable — inilah yang membuat aplikasi berpindah environment tanpa perubahan kode:

Catatan penting: OTEL_EXPORTER_OTLP_ENDPOINT bersifat dasar — untuk gRPC SDK menambahkan path sesuai sinyal, sedangkan untuk http/protobuf kalian biasanya perlu menetapkan TRACES_ENDPOINT penuh (http://host:4318/v1/traces) agar tidak salah path.

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
opentelemetry-instrument python app.py

#Retry & Backoff: Jaring Pengaman

Exporter OTLP tidak menyerah begitu saja saat backend menolak. Ia menerapkan retry dengan backoff eksponensial:

• Retry dilakukan pada error yang bisa dipulihkan: UNAVAILABLE, RESOURCE_EXHAUSTED, CANCELLED, dan HTTP 429/5xx.
• Backoff eksponensial dengan jitter untuk mencegah thundering herd — semua SDK retry di momen yang sama.
• Data yang tidak terkirim setelah batas retry di-drop (perilaku default) — kecuali kalian menambahkan buffering ekstra, topik episode 14.

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from grpc import ssl_channel_credentials
 
exporter = OTLPSpanExporter(
    endpoint="http://collector:4317",
    timeout=10,
    max_retry=5,           # coba ulang maksimal 5x
    retry_backoff_base=0.5,
    retry_backoff_multiplier=2.0,
)

#Common Pitfalls OTLP

• Salah port — mengirim protobuf HTTP ke 4317 (gRPC) atau gRPC ke 4318 (HTTP); gejalanya error protokol dan koneksi tertutup.
• Endpoint dasar vs penuh — OTLP_EXPORTER_OTLP_ENDPOINT dengan protokol HTTP sering butuh path eksplisit (/v1/traces).
• Backend tidak mendukung gzip — sesuaikan OTEL_EXPORTER_OTLP_COMPRESSION dengan kemampuan collector/backend.
• Firewall memblokir port — 4317 dan 4318 sering tidak terbuka di security group; uji dengan curl dulu.

#Penutup

Pada episode 8 ini, kalian telah menguasai protokol OTLP dan konfigurasi ekspor.

Inti yang harus dibawa pulang:

• OTLP = protobuf + transport gRPC (4317) atau HTTP (4318); stabil di v1.10.0.
• Satu protokol untuk tiga sinyal — traces, metrics, logs.
• Konfigurasi via environment variable membuat kode portabel antar environment.
• Exporter punya retry + backoff eksponensial bawaan; uji pipeline dengan curl JSON sebelum menyalahkan SDK.

Di episode 9 selanjutnya, kita masuk Fase 3 dan membahas collector: arsitektur & deployment — pipeline receivers → processors → exporters, pola agent vs gateway, serta perbedaan distribusi otelcol core vs contrib beserta status stability-nya. Sampai jumpa di episode 9!