Plugin Google Cloud

Plugin Google Cloud mengekspor data telemetri dan logging Firebase Genkit ke suite Cloud Observability.

Penginstalan

npm i --save @genkit-ai/google-cloud

Saat menjalankan kode Genkit secara lokal yang menyertakan plugin ini, Anda juga harus menginstal alat Google Cloud CLI.

Menyiapkan akun Google Cloud

Plugin ini memerlukan akun/project Google Cloud. Semua project Firebase menyertakan satu project secara default (Konsol GCP), atau Anda dapat mendaftar di https://cloud.google.com.

Sebelum menambahkan plugin, pastikan API berikut diaktifkan untuk project GCP Anda:

API ini harus tercantum di dasbor API untuk project Anda.

Klik di sini untuk mempelajari lebih lanjut cara mengaktifkan dan menonaktifkan API.

Konfigurasi Genkit

Untuk mengaktifkan Cloud Tracing, Logging, dan Monitoring (metrik), cukup panggil enableGoogleCloudTelemetry():

import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';

enableGoogleCloudTelemetry();

Saat berjalan dalam produksi, telemetri akan diekspor secara otomatis.

Autentikasi dan otorisasi

Plugin ini memerlukan kredensial aplikasi dan project ID Google Cloud.

Google Cloud

Jika men-deploy kode ke lingkungan Google Cloud (Cloud Functions, Cloud Run, dll.), project ID dan kredensial akan ditemukan secara otomatis melalui Kredensial Default Aplikasi.

Anda harus menerapkan peran berikut ke akun layanan yang menjalankan kode Anda (yaitu 'akun layanan terlampir') melalui Konsol IAM:

  • roles/monitoring.metricWriter
  • roles/cloudtrace.agent
  • roles/logging.logWriter

Pengembangan Lokal

Saat melakukan pengembangan lokal, agar kredensial pengguna Anda tersedia untuk plugin, diperlukan langkah tambahan.

  1. Tetapkan variabel lingkungan GCLOUD_PROJECT ke project Google Cloud Anda.

  2. Lakukan autentikasi menggunakan gcloud CLI:

    gcloud auth application-default login

Lingkungan produksi di luar Google Cloud

Jika memungkinkan, sebaiknya manfaatkan proses Kredensial Default Aplikasi untuk menyediakan kredensial ke plugin.

Biasanya, hal ini melibatkan pembuatan kunci/pasangan akun layanan dan deployment kredensial tersebut ke lingkungan produksi Anda.

  1. Ikuti petunjuk untuk menyiapkan kunci akun layanan.

  2. Pastikan akun layanan memiliki peran berikut:

    • roles/monitoring.metricWriter
    • roles/cloudtrace.agent
    • roles/logging.logWriter

  3. Men-deploy file kredensial ke produksi (jangan memeriksa kode sumber)

  4. Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS sebagai jalur ke file kredensial.

    GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"

Di beberapa lingkungan serverless, Anda mungkin tidak dapat men-deploy file kredensial. Dalam hal ini, sebagai alternatif untuk langkah 3 & 4 di atas, Anda dapat menetapkan variabel lingkungan GCLOUD_SERVICE_ACCOUNT_CREDS dengan konten file kredensial sebagai berikut:

GCLOUD_SERVICE_ACCOUNT_CREDS='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "your-cert-url"
}'

Konfigurasi plugin

Fungsi enableGoogleCloudTelemetry() menggunakan objek konfigurasi opsional yang mengonfigurasi instance OpenTelemetry NodeSDK.

import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';

enableGoogleCloudTelemetry({
  forceDevExport: false, // Set this to true to export telemetry for local runs
  sampler: new AlwaysOnSampler(),
  autoInstrumentation: true,
  autoInstrumentationConfig: {
    '@opentelemetry/instrumentation-fs': { enabled: false },
    '@opentelemetry/instrumentation-dns': { enabled: false },
    '@opentelemetry/instrumentation-net': { enabled: false },
  },
  metricExportIntervalMillis: 5_000,
});

Objek konfigurasi memungkinkan kontrol terperinci atas berbagai aspek ekspor telemetri yang diuraikan di bawah.

kredensial

Memungkinkan menentukan kredensial secara langsung menggunakan JWTInput dari library google-auth.

sampler

Jika mengekspor semua rekaman aktivitas tidak praktis, OpenTelemetry memungkinkan pengambilan sampel rekaman aktivitas.

Ada empat sampler yang telah dikonfigurasi sebelumnya:

autoInstrumentation & autoInstrumentationConfig

Dengan mengaktifkan instrumentasi otomatis, OpenTelemetry dapat mengambil data telemetri dari library pihak ketiga tanpa perlu mengubah kode.

metricExportIntervalMillis

Kolom ini menentukan interval ekspor metrik dalam milidetik.

metricExportTimeoutMillis

Kolom ini menentukan waktu tunggu untuk ekspor metrik dalam milidetik.

disableMetrics

Memberikan penggantian yang menonaktifkan ekspor metrik sekaligus masih mengekspor rekaman aktivitas dan log.

disableTraces

Memberikan penggantian yang menonaktifkan ekspor rekaman aktivitas sekaligus mengekspor metrik dan log.

disableLoggingInputAndOutput

Memberikan penggantian yang menonaktifkan pengumpulan log input dan output.

forceDevExport

Opsi ini akan memaksa Genkit mengekspor data log dan telemetri saat berjalan di lingkungan dev (misalnya, secara lokal).

Menguji integrasi Anda

Saat mengonfigurasi plugin, gunakan forceDevExport: true untuk mengaktifkan ekspor telemetry untuk operasi lokal. Buka Google Cloud Logs, Metrics, atau Trace Explorer untuk melihat telemetri.

Rangkaian Google Cloud Observability

Setelah kode Anda (misalnya alur) di-deploy, buka dasbor Cloud Monitoring dan pilih project Anda. Dari sini, Anda dapat dengan mudah beralih di antara eksplorator Log, Metrik, dan Rekaman Aktivitas untuk pemantauan produksi.

Log dan trace

Dari menu sebelah kiri, klik 'Logs explorer' di bagian judul 'Explore'.

Di sini, Anda akan melihat semua log yang terkait dengan kode Genkit yang di-deploy, termasuk console.log(). Setiap log yang memiliki awalan [genkit] adalah log internal Genkit yang berisi informasi yang mungkin menarik untuk tujuan proses debug. Misalnya, log Genkit dalam format Config[...] berisi metadata seperti nilai temperatur dan topK untuk inferensi LLM tertentu. Log dalam format Output[...] berisi respons LLM, sedangkan log Input[...] berisi perintah. Cloud Logging memiliki ACL yang andal dan memungkinkan kontrol terperinci atas akses ke log sensitif.

Tindakan ini akan menampilkan panel pratinjau trace yang memberikan sekilas gambaran detail trace. Untuk mendapatkan detail lengkap, klik link "Lihat di Trace" di kanan atas panel.

Elemen navigasi yang paling menarik di Cloud Trace adalah diagram sebar trace. Properti ini berisi semua trace yang dikumpulkan dalam rentang waktu tertentu.

Mengklik setiap titik data akan menampilkan detailnya di bawah diagram sebar.

Tampilan mendetail berisi bentuk flow, termasuk semua langkah, dan informasi pengaturan waktu yang penting. Cloud Trace memiliki kemampuan untuk menyisipkan semua log yang terkait dengan trace tertentu dalam tampilan ini. Pilih opsi "Tampilkan yang diperluas" di menu drop-down "Logs & peristiwa".

Tampilan yang dihasilkan memungkinkan pemeriksaan log secara mendetail dalam konteks trace, termasuk prompt dan respons LLM.

Metrik

Melihat semua metrik yang diekspor oleh Genkit dapat dilakukan dengan mengklik 'Pengelolaan metrik' di bagian judul 'Konfigurasi' di menu sebelah kiri.

Konsol pengelolaan metrik berisi tampilan tabel semua metrik yang dikumpulkan, termasuk metrik yang berkaitan dengan Cloud Run dan lingkungan di sekitarnya. Mengklik opsi 'Workload' akan menampilkan daftar yang menyertakan metrik yang dikumpulkan Genkit. Setiap metrik dengan awalan genkit merupakan metrik Genkit internal.

Genkit mengumpulkan beberapa kategori metrik, termasuk: fitur, tindakan, dan pembuatan. Setiap metrik memiliki beberapa dimensi yang berguna untuk memfasilitasi pemfilteran dan pengelompokan yang andal.

Dimensi umum mencakup:

  • flow_name - nama tingkat teratas alur.
  • flow_path - span dan span induknya hingga span root.
  • error_code - jika terjadi error, kode error yang sesuai.
  • error_message - jika terjadi error, pesan error yang sesuai.
  • model: nama model.

Metrik fitur

Fitur adalah titik entri tingkat atas ke kode Genkit Anda. Dalam sebagian besar kasus, ini akan berupa alur. Jika tidak, ini akan menjadi span teratas dalam rekaman aktivitas.

Nama Jenis Deskripsi
genkit/feature/requests Penghitung Jumlah permintaan
genkit/feature/latency Histogram Latensi eksekusi dalam md

Setiap metrik fitur berisi dimensi berikut:

Nama Deskripsi
name Nama fitur. Pada umumnya, ini adalah alur Genkit tingkat teratas
status 'success' atau 'failure' bergantung pada apakah permintaan fitur berhasil atau tidak
error Hanya ditetapkan saat status=failure. Berisi jenis error yang menyebabkan kegagalan
source Bahasa sumber Genkit. Misalnya, 'ts'
sourceVersion Versi framework Genkit

Metrik tindakan

Tindakan mewakili langkah eksekusi umum dalam Genkit. Setiap langkah ini akan melacak metrik berikut:

Nama Jenis Deskripsi
genkit/action/requests Penghitung Frekuensi tindakan ini telah dieksekusi
genkit/action/latency Histogram Latensi eksekusi dalam md

Setiap metrik tindakan berisi dimensi berikut:

Nama Deskripsi
name Nama tindakan
featureName Nama fitur induk yang sedang dieksekusi
jalur Jalur eksekusi dari root fitur ke tindakan ini. misalnya. '/myFeature/parentAction/thisAction'
status 'success' atau 'failure', bergantung pada apakah tindakan berhasil atau tidak
error Hanya ditetapkan saat status=failure. Berisi jenis error yang menyebabkan kegagalan
source Bahasa sumber Genkit. Misalnya, 'ts'
sourceVersion Versi framework Genkit

Membuat metrik

Ini adalah metrik tindakan khusus yang berkaitan dengan tindakan yang berinteraksi dengan model. Selain permintaan dan latensi, input dan output juga dilacak, dengan dimensi khusus model yang mempermudah proses debug dan penyesuaian konfigurasi.

Nama Jenis Deskripsi
genkit/ai/generate/requests Penghitung Frekuensi model ini dipanggil
genkit/ai/generate/latency Histogram Latensi eksekusi dalam md
genkit/ai/generate/input/tokens Penghitung Token input
genkit/ai/generate/output/tokens Penghitung Token output
genkit/ai/generate/input/characters Penghitung Memasukkan karakter
genkit/ai/generate/output/characters Penghitung Karakter output
genkit/ai/generate/input/images Penghitung Gambar input
genkit/ai/generate/output/images Penghitung Gambar output
genkit/ai/generate/input/audio Penghitung File audio input
genkit/ai/generate/output/audio Penghitung File audio output

Setiap metrik yang dihasilkan berisi dimensi berikut:

Nama Deskripsi
modelName Nama model
featureName Nama fitur induk yang sedang dieksekusi
jalur Jalur eksekusi dari root fitur ke tindakan ini. misalnya. '/myFeature/parentAction/thisAction'
latencyMs Waktu respons yang diperlukan model
status 'success' atau 'failure' bergantung pada apakah permintaan fitur berhasil atau tidak
error Hanya ditetapkan saat status=failure. Berisi jenis error yang menyebabkan kegagalan
source Bahasa sumber Genkit. Misalnya, 'ts'
sourceVersion Versi framework Genkit

Memvisualisasikan metrik dapat dilakukan melalui Metrics Explorer. Dengan menggunakan menu samping kiri, klik 'Metrics Explorer' di bagian judul 'Explore'.

Pilih metrik dengan mengklik dropdown 'Select a metric', lalu pilih 'Generic Node', 'Genkit', dan metrik.

Visualisasi metrik akan bergantung pada jenisnya (penghitung, histogram, dll.). Metrics Explorer menyediakan fasilitas pembuatan kueri dan penggabungan yang andal untuk membantu membuat grafik metrik berdasarkan berbagai dimensinya.

Penundaan telemetri

Mungkin ada sedikit keterlambatan sebelum telemetri untuk eksekusi flow tertentu ditampilkan di Cloud Operations Suite. Biasanya, keterlambatan ini kurang dari 1 menit.

Kuota dan batas

Ada beberapa kuota yang penting untuk diingat:

Biaya

Cloud Logging, Cloud Trace, dan Cloud Monitoring memiliki paket gratis yang melimpah. Harga khusus dapat ditemukan di link berikut: