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 perlu menginstal alat Google Cloud CLI.

Siapkan 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.

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. 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.

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:

autoInstrumentation & 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.

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 'Penjelajah log'.

Anda akan melihat semua log yang terkait dengan alur 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 suhu dan topK untuk inferensi LLM tertentu. Log dalam format Output[...] berisi respons LLM, sedangkan log Input[...] berisi perintah. Cloud Logging memiliki ACL yang kuat 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 "View in trace details".

Tindakan ini akan menampilkan panel pratinjau rekaman aktivitas yang memberikan tampilan sekilas detail rekaman aktivitas. Untuk mendapatkan detail lengkap, klik link "View in Trace" di kanan atas panel.

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

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

Tampilan mendetail berisi bentuk alur, 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 drop-down "Log & peristiwa".

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

Regresi

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 opsi 'Beban Kerja' 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 alur, tingkat tindakan, dan tingkat hasil. 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 induknya mencakup rantai 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 suhu inferensi.
  • topK - nilai topK inferensi.
  • topP - value topP inferensi.

Metrik tingkat alur

Name Dimensi
genkit/flow/permintaan flow_name, error_code, error_message
genkit/flow/latensi nama_alur

Metrik tingkat tindakan

Name Dimensi
genkit/tindakan/permintaan flow_name, error_code, error_message
genkit/tindakan/latensi nama_alur

Buat metrik tingkat

Name Dimensi
genkit/ai/buat 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/buat/output_characters flow_path, model, temperature, topK, topP
genkit/ai/buat/input_images flow_path, model, temperature, topK, topP
genkit/ai/buat/output_images flow_path, model, temperature, topK, topP
genkit/ai/buat/latensi flow_path, model, temperature, topK, topP, error_code, error_message

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

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