Google Cloud 插件

Google Cloud 插件会将 Firebase Genkit 的遥测数据和日志记录数据导出到 Google Cloud 的运维套件，该套件为 Firebase AI 监控信息中心（不公开预览版）提供支持。

安装

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

如果您想在本地运行使用此插件的流程，还需要安装 Google Cloud CLI 工具。

设置 Google Cloud 账号

此插件需要 Google Cloud 账号（如果您还没有，请注册）和 Google Cloud 项目。

在添加此插件之前，请确保您的项目已启用以下 API：

这些 API 应该会在您的项目的 API 信息中心内列出。

点击此处可详细了解如何启用和停用 API。

Genkit 配置

如需启用导出到 Google Cloud Tracing、Logging 和 Monitoring 的功能，只需调用 enableGoogleCloudTelemetry() 即可：

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

enableGoogleCloudTelemetry();

在生产环境中运行时，系统会自动导出您的遥测数据。

身份验证

该插件需要 Google Cloud 项目 ID 和您的 Google Cloud 项目凭据。如果您要从 Google Cloud 环境（Cloud Functions、Cloud Run 等）运行 flow，系统会自动设置项目 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

此选项会在 Genkit 在 dev 环境（例如本地）中运行时强制其导出遥测数据和日志数据。

测试您的集成

配置该插件时，请使用 forceDevExport: true 为本地运行启用遥测数据导出。前往 Google Cloud 日志、Metrics 或 Trace Explorer 查看遥测数据。或者，您也可以前往 Firebase AI Monitoring 信息中心（非公开预览版），以 AI 惯用方式查看遥测数据。