Mengumpulkan log, metrik, dan trace biasanya berarti memasang tiga agent berbeda: Promtail untuk log, node_exporter untuk metrik, dan agent...

Mengumpulkan log, metrik, dan trace biasanya berarti memasang tiga agent berbeda: Promtail untuk log, node_exporter untuk metrik, dan agent tracing untuk span. Setiap agent punya berkas konfigurasi, cara reload, dan format kirim sendiri. OpenTelemetry Collector menggabungkan ketiganya dalam satu biner dengan satu model konfigurasi: terima data lewat receiver, olah lewat processor, kirim lewat exporter.
Artikel ini membahas pemasangan dan konfigurasi Collector versi 0.165.0, rilis 7 November 2026, pada Linux amd64. Semua blok perintah dan keluaran di bawah dijalankan sungguhan di direktori sementara terpisah, bukan di server produksi. Versi, keluaran nyata, dan batasan pengujian dicantumkan agar Anda bisa membandingkan dengan hasil di mesin sendiri.
Mengapa satu agent lebih mudah dirawat
Model pipeline Collector memisahkan tiga hal yang sering tercampur di agent lama: dari mana data diambil, bagaimana data diubah, dan ke mana data dikirim. Pemisahan itu membuat satu proses bisa melayani beberapa tujuan sekaligus, misalnya log ke Loki dan trace ke backend APM, tanpa menjalankan dua agent yang masing-masing membuka koneksi ke berkas yang sama.
Pola yang disarankan dokumentasi resmi adalah agent per host lalu gateway terpusat. Agent membaca berkas log lokal dan mengirim lewat OTLP; gateway menerima dari banyak host, melakukan sampling dan pengayaan, lalu meneruskan ke backend. Untuk instalasi kecil, satu Collector cukup berperan sebagai keduanya.
Jika saat ini log sudah dikirim ke Loki memakai Promtail seperti pada artikel sentralisasi log dengan Grafana Loki dan Promtail, Collector dapat menggantikan peran Promtail tanpa mengubah backend: Loki menerima OTLP sejak versi 3.x, dan Collector juga punya exporter Loki bila Anda ingin format lama. Untuk metrik, Collector bisa menjadi pengganti maupun pelengkap stack Prometheus, Node Exporter, dan Grafana yang sudah dibahas sebelumnya.
Anatomi konfigurasi Collector
Konfigurasi Collector terdiri atas empat kelas komponen: receiver, processor, exporter, dan connector, ditambah extension untuk kemampuan di luar pipeline. Komponen yang didefinisikan belum berjalan sampai dimasukkan ke service.pipelines. Struktur ini dijelaskan pada dokumentasi konfigurasi Collector.
receivers:
otlp:
protocols:
http:
endpoint: 127.0.0.1:4318
processors:
memory_limiter:
check_interval: 1s
limit_mib: 256
exporters:
debug:
verbosity: detailed
service:
pipelines:
logs:
receivers: [otlp]
processors: [memory_limiter]
exporters: [debug]
Berkas konfigurasi dapat diberikan lewat --config dengan penyedia file:, env:, yaml:, http:, atau https:, dan beberapa berkas dapat digabung. Sebelum menjalankan apa pun, validasi konfigurasi lebih dulu:
otelcol-contrib validate --config=config.yaml
echo "exit=$?"
Perintah validate memeriksa skema YAML, ketersediaan komponen di distribusi, dan sintaks OTTL. Ini murah dilakukan sebelum restart layanan dan menangkap sebagian besar salah ketik yang biasanya baru terlihat dari log startup.
Memasang distribusi contrib 0.165.0
Ada beberapa distribusi: otelcol (komponen inti), otelcol-contrib (inti plus komponen komunitas), otelcol-k8s, dan otelcol-otlp. Uji ini memakai contrib karena membutuhkan receiver file_log dan processor tail_sampling yang tidak ada di distribusi inti. Berkas diunduh dari halaman rilis resmi v0.165.0.
mkdir -p otel-lab && cd otel-lab
curl -sLO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.165.0/otelcol-contrib_0.165.0_linux_amd64.tar.gz
curl -sLO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.165.0/otelcol-contrib_0.165.0_linux_amd64.tar.gz.sha256
printf '%s %s\n' "$(cat otelcol-contrib_0.165.0_linux_amd64.tar.gz.sha256)" otelcol-contrib_0.165.0_linux_amd64.tar.gz | sha256sum -c -
tar xzf otelcol-contrib_0.165.0_linux_amd64.tar.gz
./otelcol-contrib --version
Pada uji kami, berkas otelcol-contrib_0.165.0_linux_amd64.tar.gz.sha256 ternyata hanya berisi digest SHA-256 tanpa nama berkas (64 byte), sehingga sha256sum -c gagal dengan pesan no properly formatted checksum lines found bila dipakai langsung. Tempelkan nama berkas seperti pada blok di atas; hasilnya otelcol-contrib_0.165.0_linux_amd64.tar.gz: OK dan versi yang dilaporkan otelcol-contrib version 0.165.0. Ukuran tar.gz 114.481.108 byte, sedangkan biner hasil ekstrak 410.206.368 byte. Distribusi inti jauh lebih kecil: arsip otelcol_0.165.0_linux_amd64.tar.gz tercatat 47.698.347 byte pada halaman rilis yang sama. Pilih distribusi paling kecil yang memuat komponen Anda, karena ukuran biner berpengaruh pada waktu unduh dan pemindaian kerentanan.
Untuk melihat komponen apa saja yang tersedia beserta tingkat stabilitasnya, gunakan subperintah components. Ini lebih dapat dipercaya daripada mengandalkan dokumentasi versi lain:
./otelcol-contrib components | grep -A5 "name: file_log"
Keluaran pada 0.165.0 menyebut file_log berstatus Beta untuk logs, queue_batch Beta untuk logs/metrik/trace, tail_sampling Beta untuk trace, dan exporter debug masih Alpha. Status itu penting: komponen Alpha boleh berubah konfigurasi antar rilis minor, jadi jangan dipakai di jalur produksi tanpa rencana pembaruan.
Dua kesalahan konfigurasi yang langsung tertangkap
Validasi pertama kami gagal dengan pesan yang jelas. Kami menulis sizer: requests pada queue_batch.batch, padahal processor itu hanya menerima items atau bytes:
Error: processors::queue_batch::batch: `batch` supports only `items` or `bytes` sizer, found "requests"
Kesalahan kedua muncul dari OTTL, bahasa transformasi telemetri Collector. Penulisan set(attributes.env, "lab") ditolak dengan pesan the path section "env" was not used by the context. Pada versi ini OTTL memakai prefiks konteks, sehingga bentuk yang benar adalah set(attributes["env"], "lab"). Setelah dijalankan, Collector juga mencatat peringatan bahwa path ditulis ulang menjadi log.attributes["env"]. Rujukan sintaksnya ada di panduan transforming telemetry.
Pipeline log dari berkas dengan parsing terstruktur
Receiver file_log membaca berkas seperti tail, lalu operator regex_parser memecah baris menjadi atribut. Konfigurasi berikut membaca tiga baris uji: satu log INFO dengan spasi ganda, satu log ERROR, dan satu baris rusak tanpa format.
receivers:
file_log:
include:
- ./logs/app.log
start_at: beginning
operators:
- type: regex_parser
regex: '^(?P<time>\S+) +(?P<level>[A-Z]+) +(?P<svc>[\w-]+) +(?P<msg>.*)$'
on_error: drop
timestamp:
parse_from: attributes.time
layout: '%Y-%m-%dT%H:%M:%S%z'
severity:
parse_from: attributes.level
Hasil nyata pada exporter debug dengan verbosity: detailed menunjukkan severity ikut terisi, bukan sekadar teks mentah:
SeverityText: INFO
Body: Str(2026-11-17T06:12:01+08:00 INFO api-cache GET /health 200 3ms)
Attributes:
-> level: Str(INFO)
-> svc: Str(api-cache)
-> time: Str(2026-11-17T06:12:01+08:00)
SeverityText: ERROR
Body: Str(2026-11-17T06:12:02+08:00 ERROR api-cache koneksi redis timeout setelah 500ms)
Ketika satu baris gagal di-parse
Baris rusak tidak lolos. Log internal Collector mencatat "operator_type": "regex_parser", "error": "regex pattern does not match", dan "action": "drop" karena on_error: drop dipasang. Tanpa opsi itu, pada uji pertama kami baris yang gagal di-parse tetap diteruskan ke pipeline dengan body asli, tanpa atribut, dan Timestamp bernilai epoch 1970-01-01. Untuk log produksi, pola itu berbahaya: data setengah jadi masuk ke backend dan sulit dibedakan dari log normal.
Perhatikan juga spasi pada regex. Log dengan level rata kiri seperti INFO tidak cocok dengan pola (?P<level>[A-Z]+) (?P<svc>...) yang hanya mengizinkan satu spasi. Pada uji pertama, baris INFO justru gagal di-parse karena masalah sepele ini. Gunakan + setelah spasi, atau lebih aman, pakai format log terstruktur seperti JSON dengan operator json_parser agar tidak bergantung pada padding manual.
queue_batch: antrean dan batch dalam satu processor
Rilis 0.165.0 menaikkan queue_batch ke Beta untuk trace, metrik, dan log. Processor ini menggabungkan dua pekerjaan yang sebelumnya terpisah: menampung data di antrean dan mengirimkannya dalam batch. Konfigurasi uji kami:
processors:
queue_batch:
sizer: items
queue_size: 500
num_consumers: 2
batch:
flush_timeout: 1s
min_size: 1
max_size: 50
Membaca antrean lewat metrik internal
Metrik internal yang dibaca dari endpoint Prometheus Collector (127.0.0.1:8888/metrics) setelah pengujian:
otelcol_processor_queuebatch_in_flight_requests{data_type="logs",processor="queue_batch"} 0
otelcol_processor_queuebatch_queue_capacity{data_type="logs",processor="queue_batch",sizer="items"} 500
otelcol_processor_queuebatch_queue_size{data_type="logs",processor="queue_batch",sizer="items"} 0
otelcol_processor_queuebatch_sent_items{data_type="logs",processor="queue_batch"} 3
Tiga item terkirim: dua dari berkas dan satu dari kiriman OTLP manual. Angka queue_capacity dan queue_size berguna untuk alarm, karena antrean yang terus penuh menandakan backend tujuan lebih lambat daripada laju data masuk. Yang belum kami uji adalah perilaku saat backend mati total: apakah antrean bertahan setelah restart dan berapa lama retry berlangsung. Jangan menganggap ketahanan itu terbukti dari metrik di atas.
Trace dan tail sampling: hanya yang error dikirim
Pipeline trace memakai receiver otlp yang sama, processor tail_sampling, dan exporter debug. Kebijakan sampel di bawah menyimpan trace yang berstatus ERROR saja, dengan waktu tunggu keputusan dua detik:
processors:
tail_sampling:
decision_wait: 2s
policies:
- name: hanya-error
type: status_code
status_code:
status_codes: [ERROR]
Dua trace dikirim ke http://127.0.0.1:4318/v1/traces: satu span GET /checkout berstatus error dan satu span GET /health berstatus OK. Keluaran debug hanya memuat trace pertama. Metrik sampling mengonfirmasi keputusan untuk keduanya:
otelcol_processor_tail_sampling_count_traces_sampled{decision="not_sampled",policy="hanya-error",sampled="false"} 1
otelcol_processor_tail_sampling_count_traces_sampled{decision="sampled",policy="hanya-error",sampled="true"} 1
otelcol_processor_tail_sampling_new_trace_id_received 2
Ini pola yang hemat biaya untuk backend berbayar per span, tetapi ada konsekuensinya: sampling berbasis status harus menunggu seluruh trace selesai, dan Collector menyimpan trace di memori selama decision_wait. Bila Collector hanya satu instance, keputusan sampling tidak konsisten antar replika karena setiap instance memutuskan sendiri. Untuk skala lebih besar, dokumentasi menyarankan load balancing berbasis trace ID agar semua span dari satu trace tiba di instance yang sama. Skema itu tidak kami uji.
Telemetri internal dan batas memori
Collector memantau dirinya sendiri. Blok service.telemetry.metrics di bawah membuka metrik internal dalam format Prometheus pada port 8888, sehingga bisa di-scrape oleh Prometheus yang sudah ada:
service:
telemetry:
metrics:
readers:
- pull:
exporter:
prometheus:
host: 127.0.0.1
port: 8888
Tanpa batas memori, lonjakan volume log bisa membuat Collector dihentikan kernel. memory_limiter ditempatkan paling awal di pipeline dengan check_interval: 1s dan limit_mib: 256, lalu data ditolak secara terkendali saat batas mendekat. Angka 256 MiB itu pilihan untuk uji, bukan rekomendasi umum: ukur otelcol_process_runtime_heap_alloc_bytes pada beban nyata sebelum menetapkan nilai. Penjelasan lengkap ada di dokumentasi internal telemetry.
Untuk layanan systemd, pola yang sama seperti artikel observabilitas server dengan systemd dan journalctl tetap berlaku: jalankan Collector sebagai unit dengan Restart=on-failure, batasi MemoryMax, dan periksa log unit setelah perubahan konfigurasi. Collector juga bisa membaca jurnal langsung lewat receiver journald di distribusi contrib, tetapi itu tidak kami uji di sini.
Keamanan: yang belum tercakup uji ini
Konfigurasi di atas mengikat OTLP ke 127.0.0.1 dan tanpa TLS. Itu aman untuk uji lokal, tidak untuk host yang menerima kiriman dari mesin lain. Untuk produksi, tiga hal wajib ditambahkan dan tidak satu pun diuji di artikel ini: TLS pada receiver OTLP (dokumentasi menyediakan pengaturan sertifikat untuk receiver sisi server), autentikasi seperti extension bearertokenauth atau oauth2client, serta pembatasan jaringan sehingga port 4317/4318 tidak terbuka ke internet.
Peringatan: jangan mengekspos port OTLP ke jaringan publik tanpa TLS dan autentikasi. Collector menerima data apa pun yang dikirim ke port tersebut, termasuk body log yang bisa dipakai untuk menyisipkan konten berbahaya ke backend log Anda.
Batas pengujian dan langkah berikutnya
Uji dilakukan pada Linux amd64, 6 vCPU virtual, memakai otelcol-contrib 0.165.0 hasil unduhan resmi dengan checksum SHA-256 yang cocok. Semua keluaran di atas adalah kutipan langsung dari proses yang benar-benar dijalankan. Yang tidak diuji: pengiriman ke backend nyata (Loki, Tempo, Jaeger), TLS dan autentikasi, ketahanan antrean saat restart, perilaku multi-replika, serta beban tinggi. Tidak ada klaim throughput atau penghematan biaya dalam artikel ini karena tidak ada pengukuran yang mendukungnya.
Langkah aman untuk mencoba di lingkungan sendiri: jalankan Collector dengan pipeline debug saja di host non-produksi, bandingkan isi yang keluar dengan log asli, lalu ganti exporter ke backend tujuan setelah parsing dan sampling terbukti benar. Simpan berkas konfigurasi di repositori, validasi di CI dengan otelcol-contrib validate, dan catat versi distribusi agar perubahan status komponen Beta tidak mengejutkan di kemudian hari.
Rujukan resmi: konfigurasi Collector, receiver filelog, processor queue_batch, dan changelog Collector.
COMMENTS