Prometheus 3.0: OTLP, Native Histogram, UTF-8 & UI Baru

Saya sudah menjalankan Prometheus di produksi sejak era 2.x, jadi ketika tim mengumumkan versi 3.0 pada November 2024 — rilis mayor pertama dalam tujuh tahun — saya membaca catatan rilisnya dengan teliti sebelum menyentuh satu server pun. Intinya, 3.0 bukan penulisan ulang. Ini adalah mesin TSDB dan PromQL teruji yang sama, dengan UI yang dimodernkan dan sekumpulan fitur yang selama bertahun-tahun eksperimental akhirnya siap produksi.

Itu juga jebakannya. Beberapa hal yang dulu ada di balik feature flag kini aktif secara default, dan beberapa perilaku berubah dengan cara yang diam-diam merusak dashboard dan recording rule jika Anda upgrade tanpa membaca. Tulisan ini membahas apa yang benar-benar baru dan berguna, lalu perubahan yang harus saya periksa sebelum menggulirkan 3.0 ke cluster mana pun.

UI yang didesain ulang di atas kerja PromLens

Perubahan paling terlihat adalah UI web. Peramban ekspresi lama memang fungsional tapi ketinggalan zaman; yang baru mengadopsi kerja dari PromLens, termasuk tampilan pohon yang memecah kueri PromQL menjadi struktur terparsingnya sehingga Anda bisa melihat persis bagaimana tiap bagian dievaluasi. UI baru juga menampilkan nama metrik UTF-8 dengan benar dan terasa seperti aplikasi modern. Jika alur kerja Anda bergantung pada antarmuka lama, UI lama masih bisa diakses lewat feature flag old-ui untuk saat ini.

Nama metrik dan label UTF-8 secara default

Selama bertahun-tahun Prometheus membatasi nama metrik dan label pada himpunan karakter ASCII terbatas, yang berarti nama OpenTelemetry penuh titik diubah titiknya menjadi garis bawah. Di 3.0, semua karakter UTF-8 yang valid diperbolehkan pada nama secara default. Biayanya adalah perubahan sintaks kecil: untuk memilih metrik yang namanya bukan pengenal legal, Anda memakai bentuk kutip baru di dalam selector, atau menyebut label nama secara eksplisit.

# In 3.0, a metric name can contain dots, slashes, and other UTF-8.
# PromQL adds a new quoting syntax to select such names:
{"my.custom.metric", job="api"}

# ...which is equivalent to spelling out __name__ explicitly:
{__name__="my.custom.metric", job="api"}

Ingest OTLP yang stabil untuk OpenTelemetry

Prometheus 3.0 bisa bertindak sebagai receiver native untuk protokol metrik OTLP, sehingga OpenTelemetry Collector dapat mendorong data langsung ke dalamnya tanpa exporter sidecar. Anda mengaktifkan receiver dengan flag baris perintah, dan ia lalu menerima OTLP lewat HTTP di endpoint metrik OTLP. Saya memasangkannya dengan strategi terjemahan NoUTF8EscapingWithSuffixes agar nama OTel tetap memakai titik, dan saya melebarkan jendela out-of-order karena pipeline OTel sering mengirim sampel agak terlambat.

# Start Prometheus with the OTLP receiver turned on.
# It then serves OTLP metrics at /api/v1/otlp/v1/metrics
prometheus --web.enable-otlp-receiver

# prometheus.yml — recommended OTLP settings for OTel data
otlp:
  # Keep UTF-8 names instead of rewriting dots to underscores
  translation_strategy: NoUTF8EscapingWithSuffixes

storage:
  tsdb:
    # OTel pipelines often push slightly out of order
    out_of_order_time_window: 30m

Native histogram — kuat, tapi masih eksperimental

Native histogram adalah fitur yang paling saya nantikan sekaligus yang paling lambat saya adopsi di produksi. Alih-alih mendefinisikan bucket tetap di awal, fitur ini memakai bucket eksponensial yang menyesuaikan otomatis, memberikan resolusi jauh lebih tinggi dengan sebagian kecil biaya penyimpanan dan kardinalitas histogram klasik. Di 3.0 mereka tetap eksperimental: Anda mengaktifkannya lewat feature flag, format di disk dan di jaringan masih bisa berubah, dan tooling di sekitarnya belum lengkap. Saya menjalankannya di staging dan tetap men-scrape bucket klasik secara paralel.

# Native histograms are still EXPERIMENTAL in 3.0 — opt in explicitly.
prometheus --enable-feature=native-histograms

# During migration you can keep scraping the classic buckets too.
# (this option was renamed from scrape_classic_histograms in 3.0)
scrape_configs:
  - job_name: api
    always_scrape_classic_histograms: true

Remote Write 2.0

Remote Write 2.0 adalah versi baru protokol yang membawa semua yang lama diinginkan target remote-write dalam satu payload: metadata metrik, exemplar, created timestamp, dan native histogram semua dikirim bersama. Ia juga memakai string interning untuk menduplikasi ulang string label yang berulang, yang memangkas ukuran payload sekaligus CPU pada pengirim yang sibuk. Ini dinegosiasikan otomatis, jadi pengirim 3.0 turun kembali ke 1.0 saat receiver belum mendukung 2.0.

Perubahan yang merusak saat upgrade dari 2.x

Semua ini tidak gratis. Sebelum memindahkan sebuah cluster ke 3.0, saya menjalankan daftar periksa ini, karena inilah perubahan yang cenderung rusak diam-diam alih-alih terang-terangan:

• Upgrade ke 2.55 dulu. Format TSDB berpindah, jadi rollback dari 3.0 hanya bisa kembali ke 2.55 — bukan ke rilis 2.x yang lebih lama. Tahapkan lompatan dua langkah; jangan langsung melompat dari build 2.x lama.
• Regex kini cocok dengan newline. Di PromQL dan relabeling, titik dalam regex cocok dengan karakter newline di 3.0. Jika sebuah aturan bergantung pada perilaku lama, ganti titik dengan kelas non-newline eksplisit agar tetap akurat.
• Batas range selector berubah. Range kini left-open dan right-closed, yang secara halus menggeser subkueri dan kueri yang selaras; periksa ulang recording rule mana pun yang bergantung pada sampel yang jatuh persis di batas.
• Label histogram dinormalisasi. Nilai label le dan quantile menjadi bentuk float, jadi le bernilai 1 disimpan sebagai 1.0 — kueri atau alert mana pun yang mencocokkan string bilangan bulat akan berhenti cocok.

Prometheus 2.x versus 3.0 secara ringkas

Saran saya setelah menjalankan upgrade: perlakukan 3.0 sebagai risiko rendah pada mesinnya dan perhatian tinggi pada tepiannya. Inti penyimpanan dan kueri adalah kode yang sudah Anda percaya, jadi migrasinya sendiri cepat. Pekerjaannya ada di detail — semantik regex dan range selector, normalisasi label, scraping yang lebih ketat — jadi baca panduan migrasi resmi dari awal sampai akhir, upgrade ke 2.55 dulu, dan gulirkan satu cluster demi satu cluster.