Monitoring

Topik ini merangkum sumber sinyal untuk memantau kesehatan pipeline Airflow, mulai dari tampilan UI, health check, pemeriksaan cepat melalui CLI, hingga alerting atas kegagalan DAG dan task. Health check adalah pemeriksaan kesehatan otomatis melalui HTTP. Bagian akhir memperkenalkan konsep deadman switch, yaitu pemonitor untuk kegagalan yang tidak memicu pemberitahuan apa pun. Setelah topik ini, kegagalan pipeline terdeteksi sebelum pengguna melapor, dan pemberitahuannya terkirim secara otomatis.

Membaca sinyal dari UI#

Tampilan Grid menjadi tempat pemeriksaan pertama ketika pipeline dicurigai bermasalah. Grid menyusun baris task dan kolom dag run, lalu mewarnai setiap sel menurut status task, misalnya hijau untuk success, merah untuk failed, dan biru muda untuk task yang sedang berjalan. Sel merah paling kanan menunjukkan dag run terbaru yang gagal. Mengeklik sel tersebut membuka panel task instance berisi riwayat percobaan beserta log tiap percobaannya.

Tab Graph menampilkan graf dependensi DAG, sehingga dampak kegagalan terlihat sekaligus. Task hulu yang gagal membuat task hilir menunggu dan tetap berstatus queued, dan pola ini terbaca langsung dari grafnya. Halaman Assets melengkapi kedua tampilan tersebut dengan ketergantungan data antar DAG. Ketergantungan itu dibentuk oleh asset, yaitu data yang diproduksi satu DAG dan dikonsumsi DAG lain, sehingga kegagalan produsen data dapat ditelusuri sampai ke DAG konsumennya.

Seluruh sinyal UI bersifat reaktif, artinya sinyal tersebut baru berguna ketika ada orang yang melihatnya. Kebutuhan berikutnya adalah sinyal yang bekerja tanpa menunggu pembukaan halaman, dan dua bagian selanjutnya membahas sinyal semacam itu.

Health check melalui API server#

Endpoint health check merangkum kesehatan komponen Airflow dalam satu permintaan HTTP. Pada Airflow 3, endpoint tersebut berada di API server dengan alamat /api/v2/monitor/health, dan responsnya berupa objek JSON dengan kunci metadatabase, scheduler, triggerer, serta dag_processor. Contoh berikut diambil dari API server yang baru dijalankan tanpa layanan lain, sehingga scheduler terbaca unhealthy dan komponen yang tidak berjalan bernilai null.

# tidak-dijalankan
# kirim permintaan health check ke API server yang berjalan
curl -s http://localhost:8080/api/v2/monitor/health

{
  "metadatabase": {"status": "healthy"},
  "scheduler": {"status": "unhealthy", "latest_scheduler_heartbeat": null},
  "triggerer": {"status": null, "latest_triggerer_heartbeat": null},
  "dag_processor": {"status": null, "latest_dag_processor_heartbeat": null}
}

Pada deployment yang sehat, keempat komponen melaporkan status healthy beserta waktu heartbeat terakhirnya. Heartbeat adalah tanda hidup yang dikirim komponen secara berkala, sehingga waktunya menunjukkan komponen masih berjalan. Scheduler juga dapat menjalankan server health tersendiri untuk pemeriksaan langsung ke heartbeat scheduler, dan server ini diaktifkan melalui konfigurasi [scheduler] enable_health_check. Endpoint health check menilai kondisi saat permintaan dilakukan, sehingga pemonitor eksternal memanggilnya berkala dan menganggap komponen tidak sehat apabila permintaan itu sendiri gagal.

Pemeriksaan cepat melalui CLI#

Dua perintah CLI memeriksa fondasi yang paling sering menjadi penyebab gangguan, yaitu basis data metadata dan job Airflow yang harus tetap berjalan. Perintah pertama menyiapkan basis data, dan lognya bertanda waktu sehingga dialihkan ke /dev/null.

# siapkan basis data metadata, log migrasi bertanda waktu sehingga tidak ditampilkan
export AIRFLOW_HOME=/tmp/ra-monitoring
airflow db migrate > /dev/null 2>&1

Perintah airflow db check menguji koneksi ke basis data metadata. Format lognya disederhanakan agar keluaran murni berupa pesannya.

# sederhanakan format log lalu uji koneksi basis data metadata
export AIRFLOW__LOGGING__LOG_FORMAT="%(message)s"
export AIRFLOW_HOME=/tmp/ra-monitoring
airflow db check

Connection successful.

Pesan tersebut disertai kode keluar nol, artinya basis data metadata dapat dijangkau. Perintah kedua adalah airflow jobs check yang memeriksa adanya job sehat berdasarkan heartbeat yang terekam pada basis data metadata.

# tidak-dijalankan
# periksa apakah scheduler masih hidup, membutuhkan scheduler yang berjalan
airflow jobs check --job-type SchedulerJob --local

Perintah tersebut membutuhkan basis data yang sudah dimigrasi dan scheduler yang benar-benar berjalan, sehingga tidak dieksekusi di sini. Kode keluar nol berarti job sehat ditemukan, sedangkan kode selain nol berarti tidak ada. Perilaku tersebut membuat perintah cocok dipanggil berkala oleh sistem pemantauan eksternal. Opsi --local membatasi pemeriksaan pada host tempat perintah dijalankan, sedangkan opsi --allow-multiple digunakan pada konfigurasi dengan lebih dari satu scheduler.

Alerting atas kegagalan task#

Alerting adalah pemberitahuan otomatis ketika kegagalan terjadi. Dasarnya adalah callback, yaitu fungsi Python yang dipanggil Airflow ketika peristiwa tertentu terjadi. Argumen on_failure_callback terpicu ketika task gagal, on_retry_callback ketika percobaan ulang dimulai, dan on_success_callback ketika task berhasil. Ketiganya diatur per task maupun melalui default_args pada DAG. Saluran email tersedia melalui argumen task email, email_on_failure, dan email_on_retry, dengan pengiriman ditangani provider SMTP yang memang sudah terpasang pada pemasangan pip.

DAG berikut memasang on_failure_callback yang menulis pesan kegagalan ke berkas di /tmp. Berkas itu berperan sebagai pemberitahuan yang mudah diperiksa pada latihan ini.

from airflow.sdk import dag, task
from pendulum import datetime


def laporkan_kegagalan(context):
    ti = context["task_instance"]
    with open("/tmp/ra-monitoring/callback-kegagalan.log", "a", encoding="utf-8") as berkas:
        berkas.write(f"DAG {ti.dag_id}, task {ti.task_id} gagal\n")


@dag(
    dag_id="proses_ringkasan",
    schedule=None,
    start_date=datetime(2026, 11, 4),
    default_args={"on_failure_callback": laporkan_kegagalan},
)
def proses_ringkasan():
    @task
    def hitung_total() -> int:
        angka = [1, 2, 3, 4]
        return sum(angka)

    @task
    def tampilkan_total(total: int) -> None:
        print(f"total nilai: {total}")

    tampilkan_total(hitung_total())


proses_ringkasan()

DAG disalin ke folder bundle lalu dijalankan sekali dengan dags test. Log eksekusinya panjang dan bertanda waktu, sehingga dialihkan ke berkas.

# salin berkas DAG ke folder bundle
export AIRFLOW_HOME=/tmp/ra-monitoring
mkdir -p "$AIRFLOW_HOME/dags"
cp dag_proses_ringkasan.py "$AIRFLOW_HOME/dags/"

# jalankan DAG sekali secara lokal, lognya dialihkan karena bertanda waktu
export AIRFLOW_HOME=/tmp/ra-monitoring
airflow dags test proses_ringkasan 2026-11-04 > /tmp/ra-monitoring/dags-test.log 2>&1

Pada log tersebut, kedua task berstatus success dan dag run ditutup dengan status success. Callback tidak terpanggil karena on_failure_callback hanya terpicu ketika task gagal. Sebagai bukti, berkas yang seharusnya ditulis oleh callback memang tidak ada.

# pastikan berkas buatan callback tidak ada karena seluruh task berhasil
ls /tmp/ra-monitoring/callback-kegagalan.log 2>/dev/null || echo "berkas callback tidak ada"

berkas callback tidak ada

Apabila salah satu task diubah agar sengaja melempar error, dags test berakhir dengan task gagal dan berkas tersebut muncul dengan isi seperti DAG proses_ringkasan, task hitung_total gagal. Callback sungguhan menggunakan pola yang sama, yaitu memanggil webhook, mengirim pesan ke kanal tim, atau membuka tiket di sistem yang digunakan tim.

Metrik dan integrasi percakapan#

Di luar pemberitahuan per kejadian, Airflow dapat mengirim metrik berkala ke sistem pemantauan. Bagian konfigurasi [metrics] menyediakan pengiriman ke StatsD melalui kunci statsd_on dan statsd_host, serta pengiriman ke OpenTelemetry melalui kunci otel_on. Pengaturan SDK (software development kit) OpenTelemetry menggunakan variabel lingkungan standarnya. Metrik seperti jumlah dag run, durasi task, dan waktu heartbeat scheduler terbaca berdampingan dengan metrik aplikasi lain. Alerting atas metrik tersebut dibangun di sisi sistem pemantauan, misalnya ambang batas durasi atau kehilangan sinyal heartbeat.

Notifikasi ke layanan percakapan dibangun di atas callback. Provider Slack menyediakan notifier, yaitu komponen pemberitahuan siap pakai, yang dapat dipasang sebagai on_failure_callback, sehingga kegagalan task berubah menjadi pesan di kanal tim tanpa menulis fungsi apa pun. Pemilihan saluran menyesuaikan penerima dan kecepatan yang dibutuhkan, yaitu kanal tim untuk kegagalan yang menuntut aksi segera, email untuk rekap yang tidak mendesak, dan metrik untuk tren jangka panjang.

Deadman switch dan tabel sinyal#

Deadman switch adalah pemonitor luar yang menyimpulkan kegagalan ketika sinyal rutin tidak datang, bukan ketika pesan gagal dikirim. Alerting berbasis callback hanya terpicu saat task gagal, sedangkan scheduler yang mati tidak memicu apa pun karena tidak ada task yang gagal, bahkan tidak ada task yang berjalan. Celah ini ditutup dengan pemonitor luar yang menguji keberadaan sinyal. Misalnya, DAG rekap harian diharuskan melaporkan selesainya sebelum pukul tujuh pagi, dan pemonitor memberitahukan tim apabila laporan itu tidak tiba. Endpoint health check dan perintah jobs check menjadi dasar pemonitor semacam ini.

Tabel berikut merangkum sinyal yang tersedia, alat pemeriksanya, dan tindakan yang menyertainya.

Kesalahan umum#

Menggunakan endpoint /health dari tutorial lama. Pada Airflow 3, permintaan tersebut dijawab dengan kode 404 karena alamatnya dipindah. Gunakan /api/v2/monitor/health pada API server dan sesuaikan pemonitor eksternal yang sudah terpasang.

Mengandalkan callback untuk semua bentuk kegagalan. Callback hanya terpicu pada kegagalan task, sehingga scheduler yang mati atau basis data yang terputus lolos tanpa satu pun pemberitahuan. Lengkapi callback dengan pemonitor kesehatan komponen dan deadman switch.

Mengaktifkan email_on_failure tanpa menyiapkan konfigurasi SMTP. Email tidak pernah terkirim, dan kegagalan saluran ini mudah luput dari perhatian karena DAG tetap terlihat sehat. Pastikan konfigurasi SMTP teruji terlebih dahulu sebelum email diandalkan sebagai satu-satunya saluran.

Ringkasan#

• UI menyajikan status terkini melalui warna sel Grid, tab Graph, dan halaman Assets, tetapi sifatnya reaktif karena menuntut pengamat.
• Endpoint /api/v2/monitor/health merangkum kesehatan metadatabase, scheduler, triggerer, dan dag processor, sedangkan CLI menyediakan db check dan jobs check.
• on_failure_callback, email_on_failure, dan notifier dari provider mengubah kegagalan task menjadi pemberitahuan otomatis.
• Deadman switch memantau ketiadaan sinyal dan menutup kegagalan yang tidak pernah memicu callback, seperti scheduler yang mati.

Referensi#

• Check Health — Apache Airflow — Menjelaskan endpoint health check beserta server health scheduler.
• UI Overview — Apache Airflow — Memetakan tampilan Grid, Graph, dan Assets beserta isinya.
• Metrics — Apache Airflow — Merinci konfigurasi metrik StatsD dan OpenTelemetry.
• Command Line Interface and Environment Variables Reference — Apache Airflow — Merinci perilaku perintah db check dan jobs check.
• Apache Airflow Providers SMTP — Menjelaskan konfigurasi pengiriman email pada Airflow.
• Slack Notifications — Apache Airflow Providers Slack — Menyediakan notifier untuk callback pemberitahuan.