Plugin Google Cloud

Plugin Google Cloud mengekspor data telemetri dan telemetri Firebase Genkit ke Google Cloud Operations Suite.

Penginstalan

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

Jika ingin menjalankan alur yang menggunakan plugin ini secara lokal, Anda juga memerlukan Google Cloud CLI tool.

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, tambahkan plugin googleCloud ke konfigurasi Genkit Anda:

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

export default configureGenkit({
  plugins: [googleCloud()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'googleCloud',
    logger: 'googleCloud',
  },
});

Saat berjalan di produksi, telemetri Anda akan otomatis diekspor.

Autentikasi

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

Kredensial Default Aplikasi

Agar dapat berjalan di lingkungan lain, Anda harus menyetel variabel lingkungan GCLOUD_PROJECT ke project Google Cloud Anda dan melakukan autentikasi 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 Anda.

Setelah mendownload file kunci, Anda dapat menentukan kredensial dengan dua cara, yaitu 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"

Teks 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

Plugin googleCloud() mengambil objek konfigurasi opsional:

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

projectId

Opsi ini memungkinkan penentuan project ID Google Cloud secara eksplisit. Umumnya, langkah ini tidak diperlukan.

telemetriConfig

Opsi ini mengonfigurasi instance OpenTelemetry NodeSDK.

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

googleCloud({
  telemetryConfig: {
    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,
  },
});

forceDevExport

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

sampel

Untuk kasus yang tidak praktis dalam mengekspor semua trace, OpenTelemetry memungkinkan pengambilan sampel trace.

Ada empat sampler yang telah dikonfigurasi sebelumnya:

Instrumentasi otomatis & autoInstrumentationConfig

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

MetricsExportInterval

Kolom ini menentukan interval ekspor metrik dalam milidetik.

Menguji integrasi Anda

Saat mengonfigurasi plugin, gunakan forceDevExport: true untuk mengaktifkan ekspor telemetri untuk operasi lokal. Ini adalah cara cepat untuk mengirim peristiwa pertama Anda untuk dipantau di Google Cloud.

Pemantauan produksi melalui Google Cloud Operations Suite

Setelah alur di-deploy, buka Google Cloud Operations Suite lalu pilih project Anda.

Log dan trace

Dari menu samping, cari 'Logging' dan klik 'Logs explorer'.

Anda akan melihat semua log yang terkait dengan flow 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 prompt. Cloud Logging memiliki ACL yang andal dan memungkinkan kontrol terperinci atas log sensitif.

Untuk baris log tertentu, Anda dapat membuka trace masing-masing dengan mengklik ikon menu yang diperluas dan memilih "Lihat dalam rincian trace".

Tindakan ini akan menampilkan panel pratinjau trace yang memberikan sekilas gambaran detail terkait trace. Untuk mendapatkan detail yang lengkap, klik "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" dari 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 Genkit dapat dilakukan dengan memilih "Logging" dari menu samping dan mengklik "Pengelolaan metrik".

Konsol pengelolaan metrik berisi tampilan tabel semua metrik yang dikumpulkan, termasuk metrik yang berkaitan dengan Cloud Run dan lingkungan di sekitarnya. Mengklik '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 metrik tingkat flow, tingkat tindakan, dan tingkat 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.
  • temperature - nilai temperatur inferensi.
  • topK - nilai topK inferensi.
  • topP - value topP inferensi.

Metrik tingkat flow

Nama Dimensi
genkit/flow/requests flow_name, error_code, error_message
genkit/flow/latency flow_name

Metrik tingkat tindakan

Nama Dimensi
genkit/action/requests flow_name, error_code, error_message
genkit/action/latency flow_name

Metrik tingkat pembuatan

Nama Dimensi
genkit/ai/generate flow_path, model, temperature, topK, topP, error_code, error_message
genkit/ai/generate/input_tokens flow_path, model, temperature, topK, topP
genkit/ai/generate/output_tokens flow_path, model, temperature, topK, topP
genkit/ai/generate/input_characters flow_path, model, temperature, topK, topP
genkit/ai/generate/output_characters flow_path, model, temperature, topK, topP
genkit/ai/generate/input_images flow_path, model, temperature, topK, topP
genkit/ai/generate/output_images flow_path, model, temperature, topK, topP
genkit/ai/generate/latency flow_path, model, temperature, topK, topP, error_code, error_message

Memvisualisasikan metrik dapat dilakukan melalui Metrics Explorer. Dengan menggunakan menu samping, pilih 'Logging' lalu klik 'Metrics Explorer'

Pilih metrik dengan mengklik "Pilih metrik", kemudian 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: