Complemento de Google Cloud

El complemento de Google Cloud exporta la telemetría y los datos de registro de Firebase Genkit a Google Cloud's operations suite, que potencia el panel de supervisión de IA de Firebase (versión preliminar privada).

Instalación

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

Si quieres ejecutar localmente flujos que usan este complemento, también debes tener instalada la herramienta Google Cloud CLI.

Configura una cuenta de Google Cloud

Este complemento requiere una cuenta de Google Cloud (regístrate si aún no tienes una) y un proyecto de Google Cloud.

Antes de agregar el complemento, asegúrate de que las siguientes APIs estén habilitadas para tu proyecto:

Estas APIs deberían estar enumeradas en el panel de la API del proyecto.

Haz clic aquí para obtener más información sobre cómo habilitar o inhabilitar APIs.

Configuración de Genkit

Para habilitar la exportación a Google Cloud Tracing, Logging y Monitoring, simplemente llama a enableGoogleCloudTelemetry():

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

enableGoogleCloudTelemetry();

Cuando se ejecuta en producción, tu telemetría se exporta automáticamente.

Authentication

El complemento requiere el ID y las credenciales de tu proyecto de Google Cloud. Si ejecutas tu flujo desde un entorno de Google Cloud (Cloud Functions, Cloud Run, etc.), el ID del proyecto y las credenciales se establecen automáticamente.

Credencial predeterminada de la aplicación

La ejecución en otros entornos requiere configurar la variable de entorno GCLOUD_PROJECT en tu proyecto de Google Cloud y autenticarte con la herramienta gcloud:

gcloud auth application-default login

Para obtener más información, consulta los documentos Credenciales predeterminadas de la aplicación.

Credenciales de la cuenta de servicio

Si usas una cuenta de servicio y la ejecutas fuera de un entorno de Google Cloud, puedes configurar tus credenciales como una variable de entorno. Sigue las instrucciones que se indican aquí para configurar la clave de la cuenta de servicio de Google Cloud.

Una vez que hayas descargado el archivo de claves, puedes especificar las credenciales de dos maneras: una ubicación de archivo con la variable de entorno GOOGLE_APPLICATION_CREDENTIALS o copiar directamente el contenido del archivo JSON a la variable de entorno GCLOUD_SERVICE_ACCOUNT_CREDS.

Ruta de acceso al archivo:

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

Texto directo:

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

Configuración de complementos

La función enableGoogleCloudTelemetry() toma un objeto de configuración opcional que configura la instancia de 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,
});

Los objetos de configuración permiten un control detallado sobre varios aspectos de la exportación de telemetría que se describen a continuación.

credenciales

Permite especificar credenciales directamente con JWTInput desde la biblioteca google-auth.

muestreador

En los casos en que no sea práctico exportar todos los seguimientos, OpenTelemetry permite el muestreo de seguimientos.

Existen cuatro muestreadores preconfigurados:

autoInstrumentation y autoInstrumentationConfig

Habilitar la instrumentación automática permite que OpenTelemetry capture datos de telemetría de bibliotecas de terceros sin necesidad de modificar el código.

metricExportIntervalMillis

En este campo, se especifica el intervalo de exportación de métricas en milisegundos.

metricExportTimeoutMillis

Este campo especifica el tiempo de espera para la exportación de métricas en milisegundos.

disableMetrics

Proporciona una anulación que inhabilita la exportación de métricas y, al mismo tiempo, exporta seguimientos y registros.

disableTraces

Proporciona una anulación que inhabilita la exportación de seguimientos mientras se exportan métricas y registros.

disableLoggingIO

Proporciona una anulación que inhabilita la recopilación de registros de entrada y salida.

forceDevExport

Esta opción forzará a Genkit a exportar datos de telemetría y registro cuando se ejecute en el entorno de dev (p.ej., de forma local).

Prueba tu integración

Cuando configures el complemento, usa forceDevExport: true para habilitar la exportación de telemetría para las ejecuciones locales. Navega a los registros, las métricas o el Explorador de seguimientos de Google Cloud para ver la telemetría. Como alternativa, navega al panel de Firebase AI Monitoring (versión preliminar privada) para obtener una vista idiomática de la telemetría de IA.