Plugin Google Cloud

Plugin Google Cloud mengekspor data telemetri dan logging Firebase Genkit ke Google Cloud Operations Suite yang mendukung dasbor Firebase AI Monitoring (pratinjau pribadi).

Penginstalan

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

Jika ingin menjalankan flow yang menggunakan plugin ini secara lokal, Anda juga perlu menginstal alat Google Cloud CLI.

Menyiapkan akun Google Cloud

Plugin ini memerlukan akun Google Cloud (daftar jika Anda belum memilikinya) dan project Google Cloud.

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

API tersebut harus tercantum di dasbor API untuk project Anda.

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

Konfigurasi Genkit

Untuk mengaktifkan ekspor ke Google Cloud Tracing, Logging, dan Monitoring, cukup panggil enableGoogleCloudTelemetry():

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

enableGoogleCloudTelemetry();

Saat berjalan dalam produksi, telemetri Anda akan diekspor secara otomatis.

Autentikasi

Plugin ini memerlukan project ID Google Cloud dan kredensial project Google Cloud Anda. Jika Anda menjalankan flow dari lingkungan Google Cloud (Cloud Functions, Cloud Run, dll.), project ID dan kredensial akan ditetapkan secara otomatis.

Kredensial Default Aplikasi

Untuk berjalan di lingkungan lain, Anda harus menetapkan variabel lingkungan GCLOUD_PROJECT ke project Google Cloud dan mengautentikasi menggunakan alat gcloud:

gcloud auth application-default login

Untuk informasi selengkapnya, lihat dokumen Kredensial Default Aplikasi.

Kredensial Akun Layanan

Jika menggunakan akun layanan dan berjalan di luar lingkungan Google Cloud, Anda dapat menetapkan kredensial sebagai variabel lingkungan. Ikuti petunjuk di sini untuk menyiapkan Kunci Akun Layanan Google Cloud.

Setelah mendownload file kunci, Anda dapat menentukan kredensial dengan dua cara; lokasi file menggunakan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS atau langsung menyalin konten file json ke variabel lingkungan GCLOUD_SERVICE_ACCOUNT_CREDS.

Jalur file:

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

Salinan langsung:

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

Mengaktifkan instrumentasi otomatis memungkinkan OpenTelemetry 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 tetap mengekspor rekaman aktivitas dan log.

disableTraces

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

disableLoggingIO

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 telemetri untuk operasi lokal. Buka Google Cloud Logs, Metrics, atau Trace Explorer untuk melihat telemetri. Atau, buka dasbor Firebase AI Monitoring (pratinjau pribadi) untuk melihat telemetri dengan istilah AI.