Google Cloud 外掛程式

Google Cloud 外掛程式會將 Firebase Genkit 的遙測和記錄資料匯出至 Google Cloud 作業套件，後者可支援 Firebase AI Monitoring 資訊主頁 (私人搶先體驗版)。

安裝

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

如果您想在本機執行使用此外掛程式的流程，還必須安裝 Google Cloud CLI 工具。

設定 Google Cloud 帳戶

這個外掛程式需要 Google Cloud 帳戶 (如果還沒有帳戶，請註冊) 和 Google Cloud 專案。

新增外掛程式前，請確認專案已啟用下列 API：

這些 API 應列在專案的 API 資訊主頁中。

如要進一步瞭解如何啟用及停用 API，請按這裡。

Genkit 設定

如要啟用匯出至 Google Cloud 追蹤、記錄和監控功能，只要呼叫 enableGoogleCloudTelemetry() 即可：

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

enableGoogleCloudTelemetry();

在實際環境中執行時，系統會自動匯出遙測資料。

驗證

外掛程式需要 Google Cloud 專案 ID 和 Google Cloud 專案憑證。如果您透過 Google Cloud 環境 (Cloud Functions、Cloud Run 等) 執行流程，系統會自動設定專案 ID 和憑證。

應用程式預設憑證

如要在其他環境中執行，您必須將 GCLOUD_PROJECT 環境變數設為 Google Cloud 專案，並使用 gcloud 工具進行驗證：

gcloud auth application-default login

詳情請參閱「應用程式預設憑證」說明文件。

服務帳戶憑證

如果您使用服務帳戶，且是在 Google Cloud 環境以外執行，可以將憑證設為環境變數。請按照這裡的操作說明設定 Google Cloud 服務帳戶金鑰。

下載金鑰檔案後，您可以透過兩種方式指定憑證：使用 GOOGLE_APPLICATION_CREDENTIALS 環境變數的檔案位置，或直接將 JSON 檔案的內容複製到環境變數 GCLOUD_SERVICE_ACCOUNT_CREDS。

檔案路徑：

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

直接複製：

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"
}'

外掛程式設定

enableGoogleCloudTelemetry() 函式會採用選用的設定物件，用於設定 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,
});

設定物件可精細控管下列所述的各種追蹤資料匯出作業。

憑證

允許直接使用 google-auth 程式庫中的 JWTInput 指定憑證。

取樣器

如果無法匯出所有追蹤記錄，OpenTelemetry 允許追蹤記錄取樣。

四種預先設定的取樣器如下：

autoInstrumentation 和 autoInstrumentationConfig

啟用自動檢測功能後，OpenTelemetry 就能擷取第三方程式庫中的遙測資料，而不需要修改程式碼。

metricExportIntervalMillis

這個欄位會以毫秒為單位，指定指標匯出間隔。

metricExportTimeoutMillis

這個欄位會以毫秒為單位，指定指標匯出作業的逾時時間。

disableMetrics

提供覆寫值，可在匯出追蹤記錄和記錄檔的同時，停用指標匯出功能。

disableTraces

提供覆寫值，可在匯出指標和記錄的同時，停用匯出追蹤記錄的功能。

disableLoggingIO

提供覆寫值，停用輸入和輸出記錄收集功能。

forceDevExport

這個選項會在 dev 環境 (例如本機) 中執行時，強制 Genkit 匯出遙測資料和記錄資料。

測試整合

設定外掛程式時，請使用 forceDevExport: true 為本機執行作業啟用遙測匯出功能。前往 Google Cloud 記錄、Metrics 或 Trace Explorer 查看遙測資料。或者，您也可以前往 Firebase AI Monitoring 資訊主頁 (私人預先發布版)，以 AI 專用的視圖查看遙測資料。