Belajar OpenTelemetry - Collector Configuration (YAML)

#Pendahuluan

Setelah memahami arsitektur collector di episode 9, sekarang kita menulis konfigurasi yang sebenarnya. Collector dikonfigurasi lewat satu file YAML dengan empat bagian: receivers, processors, exporters, dan service. Terlihat sederhana — tetapi konfigurasi inilah yang menentukan apakah observability kalian hemat, aman, dan andal.

Mengapa penting menguasai config collector? Karena hampir semua tunjangan produksi observability — dari redaksi PII sampai sampling tail — hidup di file ini, bukan di kode aplikasi. Kalian akan menghabiskan lebih banyak waktu di file YAML ini daripada di SDK.

#Empat Bagian Konfigurasi

#receivers: Tempat Data Masuk

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:14250
  hostmetrics:
    collection_interval: 30s

hostmetrics adalah receiver yang mengumpulkan metrics sistem (CPU, memory, disk, network) dari host tempat collector berjalan — sumber utama "mengapa server ini lambat?".

#processors: Transformasi Data

processors:
  batch:
    timeout: 2s
    send_batch_size: 1024
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  attributes/route:
    actions:
      - key: deployment.environment
        action: insert
        value: production
  resource/detect:
    detectors: [env, system]

Setiap processor adalah blok bernama yang bisa dipakai oleh banyak pipeline sekaligus.

#exporters: Tempat Data Keluar

exporters:
  otlp/backend:
    endpoint: jaeger:4317
    tls:
      insecure: true
  debug:
    verbosity: basic
  prometheus:
    endpoint: 0.0.0.0:8889

Nama exporter bisa diberi suffix (otlp/backend, otlp/agent) agar satu tipe exporter bisa dipakai ke tujuan berbeda dalam satu config.

#service: Menghubungkan Semuanya

service:
  telemetry:
    logs:
      level: info
  pipelines:
    traces:
      receivers: [otlp, jaeger]
      processors: [memory_limiter, batch]
      exporters: [otlp/backend]
    metrics:
      receivers: [otlp, hostmetrics]
      processors: [memory_limiter, batch]
      exporters: [prometheus, debug]

Poin penting: sebuah receiver/processor/exporter yang didefinisikan tidak aktif sampai dirujuk oleh setidaknya satu pipeline di service.pipelines. Ini sumber kebingungan umum — data tidak mengalir bukan karena salah definisi, melainkan karena belum dihubungkan ke pipeline.

#Full Pipeline: OTLP In → Batch → Export

Mari susun config lengkap yang menerima OTLP dari SDK, menambah Resource, melakukan batch, dan meneruskan ketiga sinyal ke backend. File ini lebih lengkap dari versi episode 0:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
 
processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
    spike_limit_mib: 128
  resource/add:
    attributes:
      - key: collector.hostname
        value: ${env:HOSTNAME}
        action: upsert
  batch:
    timeout: 2s
    send_batch_size: 1024
 
exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true
  debug:
    verbosity: basic
  prometheus:
    endpoint: 0.0.0.0:8889
    namespace: otel
 
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, resource/add, batch]
      exporters: [otlp/jaeger, debug]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, resource/add, batch]
      exporters: [prometheus, debug]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, resource/add, batch]
      exporters: [debug]

Perhatikan:

• memory_limiter dipasang paling awal di setiap pipeline — ia melindungi collector dari OOM (detail di episode 14).
• resource/add menyisipkan collector.hostname dari environment variable — memakai sintaks ${env:HOSTNAME}.
• batch dipasang menjelang akhir agar ekspor efisien.
• debug menampilkan data langsung di log collector — teman debugging paling setia.

#Menjalankan dan Memvalidasi

Jalankan collector dengan file config:

docker run --rm \
  -p 4317:4317 -p 4318:4318 -p 8889:8889 \
  -v "$PWD/config.yaml:/etc/otelcol-contrib/config.yaml" \
  otel/opentelemetry-collector-contrib:0.156.0 \
  --config=/etc/otelcol-contrib/config.yaml

Cek validitas config tanpa menjalankan (berguna di CI):

docker run --rm -v "$PWD/config.yaml:/etc/config.yaml" \
  otel/opentelemetry-collector-contrib:0.156.0 \
  --config=/etc/config.yaml --validate

--validate mengembalikan error jelas jika ada komponen yang tidak dikenal atau pipeline salah — praktik yang wajib dimasukkan ke pipeline CI kalian.

#Mendebug Config

Ketika pipeline tidak mengalir, urutan pemeriksaan yang efisien:

1. --validate — pastikan config valid secara sintaks.
2. debug exporter — aktifkan di pipeline dan lihat apakah data sampai ke collector.
3. Log collector level debug — service.telemetry.logs.level: debug untuk melihat kesalahan receiver/processor.
4. Port listener — netstat -tlnp untuk memastikan port 4317/4318 terbuka.

#Common Pitfalls Config

• Komponen didefinisikan tapi tak dipakai pipeline — tidak aktif, tanpa error.
• Nama pipeline salah tulis — traces bukan trace, metrics bukan metric.
• Endpoint localhost di dalam container — menunjuk ke collector itu sendiri, bukan backend; pakai nama service Compose (jaeger:4317).
• Lupa tls.insecure: true untuk backend lokal tanpa TLS — handshake gRPC gagal diam-diam.

#Penutup

Pada episode 10 ini, kalian telah menyusun konfigurasi collector secara utuh.

Inti yang harus dibawa pulang:

• Config YAML empat bagian: receivers, processors, exporters, service.
• Komponen hanya aktif bila dirujuk di service.pipelines; satu sinyal per pipeline.
• Pipeline produksi dimulai dengan memory_limiter, diakhiri dengan batch.
• Validasi dengan --validate dan debug dengan exporter debug.

Di episode 11 selanjutnya, kita akan menjelajahi ekosistem receivers & exporters — otlp, jaeger, zipkin, prometheus, kafka, filelog, hostmetrics sebagai receiver; serta otlp, debug, prometheusremotewrite, kafka, dan cloud exporters sebagai tujuan data. Sampai jumpa di episode 11!