Migrasi ke Grafana Alloy dari Promtail dan Agent

Saya menjalankan sekumpulan kecil layanan di VPS yang saya-hosting sendiri, dan selama bertahun-tahun solusi logging-nya adalah Promtail yang membaca file Docker dan mengirimkannya ke Loki. Cerita itu sudah berakhir. Grafana menggabungkan Promtail, Grafana Agent Static, dan Grafana Agent Flow menjadi satu collector bernama Alloy, lalu menetapkan tanggal akhir masa pakai untuk semua yang digantikannya. Jika Anda masih di Promtail atau Agent, Anda menjalankan perangkat lunak tanpa dukungan yang waktunya terbatas.

Kabar baiknya: Alloy bukan penulisan ulang dari nol. Ini adalah distribusi OpenTelemetry Collector sungguhan yang sepenuhnya kompatibel dengan OTLP, sehingga biner yang sama kini menangani log, metrik, trace, dan profil melalui satu konfigurasi. Tulisan ini adalah migrasi yang benar-benar saya lakukan — perkakasnya, komponennya, dan di mana konverter otomatis meninggalkan Anda untuk menyelesaikan pekerjaan secara manual.

Mengapa Alloy, dan mengapa sekarang

Tenggat waktu adalah pemaksanya. Grafana Agent (Static, Flow, dan Operator) mencapai akhir masa pakai pada 1 November 2025, artinya tidak ada lagi patch keamanan atau perbaikan bug. Promtail memasuki dukungan jangka panjang pada Februari 2025 dan mencapai akhir masa pakai pada 2 Maret 2026. Semua pengembangan fitur baru hanya terjadi di Alloy. Di luar tenggat waktu, keuntungan sebenarnya adalah konsolidasi: alih-alih Promtail untuk log ditambah Collector terpisah untuk trace OTLP, satu proses Alloy menjalankan seluruh pipeline telemetri dengan satu bahasa konfigurasi.

Sintaks konfigurasi: komponen, bukan blok YAML

Promtail adalah YAML deklaratif. Alloy menggunakan sintaks konfigurasi yang awalnya bernama River — bahasa mirip HCL yang dibangun di sekitar komponen. Sebuah komponen adalah blok bernama yang melakukan satu tugas: membaca file, relabel, batch, menulis ke backend. Setiap komponen mengekspos argumen yang Anda atur dan nilai ekspor yang dikonsumsi komponen lain. Anda menyambungkannya menjadi pipeline dengan argumen forward_to, yang mengarahkan output satu komponen ke receiver komponen berikutnya. Graf referensi itulah pipeline-nya; tidak ada bagian pipelines terpisah seperti pada YAML Collector hulu.

// alloy: a minimal Loki logging pipeline
// discover local files, process, then write to Loki

local.file_match "applogs" {
  path_targets = [{"__path__" = "/var/log/app/*.log", "job" = "app"}]
}

loki.source.file "applogs" {
  targets    = local.file_match.applogs.targets
  forward_to = [loki.process.parse.receiver]
}

loki.process "parse" {
  stage.json {
    expressions = { level = "level", ts = "timestamp" }
  }
  stage.labels {
    values = { level = "" }
  }
  forward_to = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint {
    url = "http://loki:3100/loki/api/v1/push"
  }
}

Langkah 1: biarkan alloy convert melakukan pekerjaan mekanis

Jangan menerjemahkan konfigurasi lama Anda secara manual. Alloy menyertakan subperintah convert yang membaca file Promtail, Agent Static, atau Agent Flow lama Anda dan menghasilkan sintaks Alloy yang setara. Untuk Promtail, ia menargetkan skema v2.8.x. Konverter bersifat best-effort: ia mencetak diagnostik untuk apa pun yang tidak bisa dipetakan dengan bersih, dan Anda menyelesaikannya secara manual. Saya selalu mengonversi ke file terlebih dahulu agar bisa membaca diff sebelum menjalankan apa pun.

# Promtail -> Alloy (write to a file, review the diagnostics)
alloy convert \
  --source-format=promtail \
  --output=/etc/alloy/config.alloy \
  /etc/promtail/config.yaml

# Grafana Agent Flow -> Alloy
alloy convert --source-format=flow \
  --output=/etc/alloy/config.alloy /etc/agent/config.river

# OpenTelemetry Collector -> Alloy
alloy convert --source-format=otelcol \
  --output=/etc/alloy/config.alloy /etc/otelcol/config.yaml

# validate before restarting the service
alloy fmt /etc/alloy/config.alloy

Langkah 2: pahami sisi OpenTelemetry Collector

Di sinilah Alloy membuktikan deskripsinya. Komponen Prometheus dan Loki native (keluarga loki.* dan prometheus.*) hidup berdampingan dengan set komponen OTLP lengkap di bawah namespace otelcol.*. Jika Anda menerima OTLP dari layanan NestJS yang terinstrumentasi, otelcol.receiver.otlp menerimanya, otelcol.processor.batch mengelompokkannya, dan otelcol.exporter.otlphttp mengirimkannya lebih lanjut. Penjembatanan adalah kelas satu: otelcol.exporter.loki mengonversi log OTLP menjadi entri Loki, dan otelcol.receiver.loki melakukan sebaliknya, sehingga Anda bisa mencampur jalur push Loki lama dengan jalur OTLP modern dalam satu file.

// alloy: receive OTLP over gRPC, batch, export to an OTLP/HTTP backend
otelcol.receiver.otlp "default" {
  grpc { endpoint = "0.0.0.0:4317" }
  http { endpoint = "0.0.0.0:4318" }
  output {
    metrics = [otelcol.processor.batch.default.input]
    logs    = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.backend.input]
    logs    = [otelcol.exporter.otlphttp.backend.input]
    traces  = [otelcol.exporter.otlphttp.backend.input]
  }
}

otelcol.exporter.otlphttp "backend" {
  client { endpoint = "https://otlp.example.com" }
}

Pemetaan nama komponen

Sebagian besar migrasi adalah mempelajari komponen Alloy mana yang menggantikan setiap konsep lama. Ini adalah contekan yang saya buka sepanjang waktu.

Di mana konverter meninggalkan pekerjaan manual

• Service discovery Docker. Aturan relabel docker_sd Promtail terkonversi, tetapi saya memeriksa ulang setiap label __meta_docker_* karena label yang hilang atau diganti nama diam-diam merusak query Loki di hilir.
• Rahasia. Token inline menjadi string biasa. Saya memindahkannya ke variabel lingkungan yang dibaca via helper sys.env agar tidak ada yang sensitif berada di konfigurasi yang di-commit.
• Stage multiline. Penggabungan multiline regex yang kompleks perlu verifikasi manual terhadap sampel log nyata sebelum saya memercayainya.
• Debugging langsung. UI bawaan Alloy di port 12345 menampilkan kesehatan setiap komponen dan data langsung yang mengalir di antaranya — menggantikan sebagian besar tebakan saya.

Menjalankannya: Docker Compose

Di VPS saya semuanya adalah Docker Compose, jadi Alloy hanyalah layanan lain. Mount konfigurasi, ekspos UI debug secara lokal, dan arahkan ke volume log yang sama yang digunakan Promtail. Flag run penting: --stability.level untuk komponen non-stabil, dan path konfigurasi di akhir.

# docker-compose.yml (excerpt)
services:
  alloy:
    image: grafana/alloy:latest
    command:
      - run
      - --server.http.listen-addr=0.0.0.0:12345
      - --storage.path=/var/lib/alloy/data
      - /etc/alloy/config.alloy
    ports:
      - "127.0.0.1:12345:12345"  # debug UI, localhost only
    volumes:
      - ./config.alloy:/etc/alloy/config.alloy:ro
      - /var/log:/var/log:ro
      - alloy-data:/var/lib/alloy/data

volumes:
  alloy-data: {}

Itulah keseluruhan bentuk migrasinya: konversi secara mekanis, pelajari graf komponen, verifikasi label terhadap trafik nyata, lalu beralih. Imbalannya adalah satu agent alih-alih tiga, satu bahasa konfigurasi untuk log dan trace dan metrik, serta perangkat lunak yang masih akan menerima patch kuartal depan.