Plugin Google Cloud

Plugin Google Cloud mengekspor data telemetri dan logging 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 ini akan 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 dalam 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.), project ID dan kredensial akan ditetapkan secara otomatis. Jika dijalankan di lingkungan lain, variabel lingkungan GCLOUD_PROJECT harus ditetapkan ke project Google Cloud Anda dan perlu 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,
    forceDevExport?: boolean,
    telemetryConfig?: TelemetryConfig
}

projectId

Opsi ini memungkinkan penentuan ID project Google Cloud secara eksplisit. Dalam kebanyakan kasus, hal ini tidak diperlukan.

forceDevExport

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

{i>telemetryConfig<i}

Opsi ini mengonfigurasi instance OpenTelemetry NodeSDK.

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

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

sampel

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

Ada empat sampel yang telah dikonfigurasi sebelumnya:

autoInstrumentation & autoInstrumentationConfig

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

metrikExportInterval

Kolom ini menentukan interval ekspor metrik dalam milidetik.

Pemantauan produksi melalui Google Cloud Operations Suite

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

Log dan rekaman aktivitas

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

Anda akan melihat semua log yang terkait dengan alur yang di-deploy, termasuk console.log(). Log apa pun 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 suhu dan nilai topK untuk inferensi LLM tertentu. Log dalam format Output[...] berisi respons LLM, sedangkan log Input[...] berisi perintah. Cloud Logging memiliki ACL andal yang memungkinkan kontrol mendetail atas log sensitif.

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

Tindakan ini akan menampilkan panel pratinjau rekaman aktivitas yang memberikan gambaran singkat tentang detail rekaman aktivitas. Untuk membuka detail lengkap, klik link "View in Trace" di kanan atas panel.

Elemen navigasi yang paling terlihat di Cloud Trace adalah diagram sebar trace. Data ini berisi semua rekaman aktivitas 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 diluaskan" di drop-down "Log & peristiwa".

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

Regresi

Menampilkan 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 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 metrik tingkat alur, tingkat tindakan, dan tingkat hasil. Setiap metrik memiliki beberapa dimensi yang berguna untuk memfasilitasi pemfilteran dan pengelompokan yang canggih.

Dimensi umum mencakup:

  • flow_name - nama tingkat atas alur.
  • flow_path - span dan span induknya hingga 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 - nilai topP inferensi.

Metrik tingkat alur

Nama Dimensi
genkit/flow/permintaan nama_alur, kode_kesalahan, pesan_kesalahan
genkit/flow/latensi nama_alur

Metrik tingkat tindakan

Nama Dimensi
genkit/tindakan/permintaan nama_alur, kode_kesalahan, pesan_kesalahan
genkit/tindakan/latensi nama_alur

Metrik tingkat pembuatan

Nama Dimensi
genkit/ai/buat flow_path, model, suhu, topK, topP, error_code, error_message
genkit/ai/generate/input_tokens flow_path, model, suhu, topK, topP
genkit/ai/generate/output_tokens flow_path, model, suhu, topK, topP
genkit/ai/generate/input_characters flow_path, model, suhu, topK, topP
genkit/ai/generate/output_characters flow_path, model, suhu, topK, topP
genkit/ai/generate/input_images flow_path, model, suhu, topK, topP
genkit/ai/generate/output_images flow_path, model, suhu, topK, topP
genkit/ai/generate/latensi flow_path, model, suhu, topK, topP, error_code, error_message

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

Pilih metrik dengan mengklik dropdown "Pilih metrik", memilih 'Generic Node', 'Genkit', dan metrik.

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

Penundaan Telemetri

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

Kuota dan batas

Ada beberapa kuota yang penting untuk diperhatikan:

Biaya

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