Kemampuan Observasi Cortex Framework
Agar berhasil menjalankan dan mengoperasikan platform data tingkat perusahaan, penting untuk memiliki visibilitas ke dalam eksekusi pipeline, kualitas data, dan error operasional.
Cortex Framework mengategorikan kemampuan pengamatan di dua siklus proses yang berbeda:
- Observabilitas Waktu Deployment: Melacak pemuatan konfigurasi, kompilasi template, pemeriksaan validasi, tindakan deployment, dan telemetri API selama eksekusi alat CLI.
- Kemampuan Observasi Run-Time: Melacak eksekusi, progres pipeline, performa kueri, pernyataan kualitas data, dan pemberitahuan otomatis untuk pipeline data yang di-deploy yang berjalan di dalam Google Cloud.
Kemampuan Observasi Waktu Deployment
Observabilitas waktu deployment berfokus pada eksekusi alat CLI (misalnya, uv run cortex-build, uv run cortex-deploy, uv run cortex-build-and-deploy, uv run cortex-demo, uv run cortex-kc-sync).
Logging Konsol Lokal
Saat Anda menjalankan perintah CLI, Cortex Framework mencatat progres langsung ke konsol (stdout).
- Tingkat Log: Secara default, log dikeluarkan pada tingkat
INFO. - Sorotan Visual: Pesan diberi kode warna untuk menandai error dan peringatan secara dinamis:
- ❌ Error (Merah) yang menunjukkan kegagalan kritis yang menghentikan eksekusi.
- ⚠️ Peringatan (Oranye) yang menunjukkan potensi anomali konfigurasi atau masalah yang tidak memblokir.
- Stempel Waktu dan Sumber: Setiap baris log menampilkan waktu eksekusi dan nama modul atau class Python aktif untuk penelusuran yang akurat.
File Log Lokal Persisten
Pada setiap eksekusi perintah, orkestrator Python akan otomatis mengalirkan log eksekusi lengkap ke file log sementara di direktori temp sistem Anda:
/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log
Jalur yang tepat dicetak ke konsol selama startup alat CLI. File ini berisi detail log yang komprehensif (termasuk stack trace untuk error yang tidak terduga) dan sangat berharga untuk men-debug masalah yang terjadi selama eksekusi alat CLI atau saat Anda melampirkan ke permintaan dukungan.
Google Cloud Validasi Lingkungan
Sebelum melakukan tindakan build, deployment, atau sinkronisasi, mesin orkestrasi menjalankan utilitas GcpEnvironmentChecker. Pemeriksaan ini memvalidasi:
- API yang diperlukan: Mengonfirmasi bahwa API Google Cloud penting diaktifkan (misalnya,
bigquery.googleapis.com,dataform.googleapis.com). - Keberadaan Set Data: Memverifikasi bahwa set data mentah dan target yang diperlukan ada atau dapat dibuat.
- Lokasi & Region: Memastikan set data target cocok dengan region geografis set data sumber.
- Kapasitas dan Setelan: Memvalidasi setelan reservasi dan konfigurasi katalog.
Setiap ketidakcocokan dicatat sebagai error dengan petunjuk yang direkomendasikan tentang cara menyelesaikannya sebelum melakukan Google Cloud panggilan layanan.
Telemetri
Selama proses deployment dan sinkronisasi, Cortex Framework mencatat telemetri adopsi, varian, dan versi framework anonim ke Google Cloud. Untuk mengetahui detail cara kerjanya dan petunjuk cara menonaktifkannya, lihat Telemetri.
Kemampuan Observasi Waktu Proses
Setelah dibuat dan di-deploy, produk data dan lapisan data yang sesuai dengan Cortex Framework akan berjalan sepenuhnya dalam Dataform dan BigQuery. Hasilnya, kemampuan pengamatan runtime terintegrasi langsung dengan rangkaian operasional Google Cloud .
Logging Eksekusi Pipeline
Semua pipeline yang di-deploy dilacak menggunakan Cloud Logging dan alat eksekusi:
- Log Eksekusi Dataform: Dataform mencatat setiap peristiwa kompilasi dan eksekusi. Detail ini dapat diakses di konsol Google Cloud atau secara terprogram menggunakan Dataform API.
- Histori Tugas BigQuery: Setiap tabel dan tampilan yang diwujudkan oleh pipeline Dataform Anda menjalankan kueri SQL di dalam BigQuery. Penggunaan resource yang mendetail, performa kueri, byte yang diproses, dan stempel waktu eksekusi dicatat dalam Histori Tugas BigQuery.
Pemantauan Pipeline
Anda dapat memantau kondisi pipeline, konfigurasi rilis, dan histori eksekusi secara visual atau terprogram:
- UI Web Dataform: Buka konsol Dataform untuk:
- Periksa model data yang dikompilasi dan visualisasikan grafik yang dikompilasi.
- Verifikasi status konfigurasi rilis, template yang dikompilasi, dan lingkungan aktif.
- Pantau histori dan detail eksekusi alur kerja saat ini dan sebelumnya.
- Integrasi Cloud Monitoring: Lacak metrik pipeline Dataform, seperti durasi eksekusi, kompilasi aktif, dan tingkat kegagalan tugas alur kerja, melalui panel dasbor kustom.
Pemberitahuan & Kualitas Data
Untuk memastikan integritas data dan menandai kegagalan pipeline secara otomatis, konfigurasi pemberitahuan menggunakan mekanisme berikut:
Pernyataan Kualitas Data
Anda dapat menentukan aturan validasi data kustom (misalnya, memastikan kolom tidak pernah bernilai null, memeriksa bahwa kunci utama bersifat unik, atau memvalidasi rentang numerik) dengan membuat file pernyataan .sqlx.
- Anda dapat menyediakan file pernyataan kustom menggunakan parameter
--assertions:bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx - Selama eksekusi pipeline, Dataform menjalankan kueri validasi ini. Jika kueri pernyataan menampilkan satu atau beberapa baris, validasi akan gagal, dan eksekusi pipeline akan langsung ditandai sebagai gagal.
- Untuk mengetahui informasi selengkapnya tentang cara menulis aturan validasi data, lihat dokumentasi pernyataan Dataform resmi.
Contoh File Pernyataan (assertions.sqlx)
Contoh kueri pernyataan Dataform yang memeriksa nilai NULL dan duplikat data pelanggan. Jika kueri ini menampilkan baris, pernyataan akan gagal dan menghentikan alur kerja eksekusi:
config {
type: "assertion",
description: "Ensure customer_number_kunnr is not null and unique"
}
-- Check for NULL values
(
SELECT
"customer_number_kunnr is NULL" AS error_message
FROM
${ref("customers")}
WHERE
customer_number_kunnr IS NULL
)
UNION ALL
-- Check for duplicate keys
(
SELECT
CONCAT("Duplicate customer number found: ", customer_number_kunnr) AS error_message
FROM
${ref("customers")}
GROUP BY
customer_number_kunnr,
client_mandt
HAVING
COUNT(*) > 1
)
Cloud Alerting
Siapkan Google Cloud Kebijakan Pemberitahuan standar untuk memberi tahu tim engineering atau operasi Anda saat terjadi masalah:
- Pemberitahuan Berbasis Log: Buat pemberitahuan di Cloud Logging yang dipicu saat peristiwa error, eksekusi alur kerja yang gagal, atau masalah compiler terdeteksi di log Anda.
- Pemberitahuan Berbasis Metrik: Tentukan nilai minimum di Cloud Monitoring berdasarkan durasi eksekusi atau kegagalan kompilasi.
- Saluran Notifikasi: Konfigurasi pemberitahuan ini untuk mengarahkan masalah ke saluran komunikasi pilihan tim Anda