Complemento de Google Cloud

El complemento de Google Cloud exporta la telemetría y los datos de registro de Firebase Genkit al paquete de Google Cloud Observability.

Instalación

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

Cuando ejecutes el código de Genkit de forma local que incluya este complemento, también necesitarás la herramienta Google Cloud CLI instalada.

Configura una cuenta de Google Cloud

Este complemento requiere una cuenta o un proyecto de Google Cloud. Todos los proyectos de Firebase incluyen uno de forma predeterminada (GCP Console), o puedes registrarte en https://cloud.google.com.

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

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

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

Configuración de Genkit

Para habilitar Cloud Tracing, Logging y Monitoring (métricas), simplemente llama a enableGoogleCloudTelemetry():

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

enableGoogleCloudTelemetry();

Cuando se ejecute en producción, la telemetría se exportará automáticamente.

Autenticación y autorización

El complemento requiere un ID de proyecto de Google Cloud y credenciales de la aplicación.

Google Cloud

Si implementas tu código en un entorno de Google Cloud (Cloud Functions, Cloud Run, etc.), el ID del proyecto y las credenciales se descubrirán automáticamente a través de las credenciales predeterminadas de la aplicación.

Deberás aplicar los siguientes roles a la cuenta de servicio que ejecuta tu código (es decir, la "cuenta de servicio adjunta") a través de la consola de IAM:

  • roles/monitoring.metricWriter
  • roles/cloudtrace.agent
  • roles/logging.logWriter

Desarrollo local

Cuando realizas el desarrollo local, se requieren pasos adicionales para que las credenciales del usuario estén disponibles para el complemento.

  1. Establece la variable de entorno GCLOUD_PROJECT en tu proyecto de Google Cloud.

  2. Autentica con la CLI de gcloud:

    gcloud auth application-default login

Entornos de producción fuera de Google Cloud

Si es posible, se recomienda aprovechar el proceso de Credenciales predeterminadas de la aplicación para que las credenciales estén disponibles para el complemento.

Por lo general, esto implica generar una clave o un par de cuentas de servicio y, luego, implementar esas credenciales en tu entorno de producción.

  1. Sigue las instrucciones para configurar una clave de cuenta de servicio.

  2. Asegúrate de que la cuenta de servicio tenga los siguientes roles:

    • roles/monitoring.metricWriter
    • roles/cloudtrace.agent
    • roles/logging.logWriter

  3. Implementa el archivo de credenciales en producción (no lo verifiques en el código fuente).

  4. Establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS como la ruta de acceso al archivo de credenciales.

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

En algunos entornos sin servidor, es posible que no puedas implementar un archivo de credenciales. En este caso, como alternativa a los pasos 3 y 4 anteriores, puedes configurar la variable de entorno GCLOUD_SERVICE_ACCOUNT_CREDS con el contenido del archivo de credenciales de la siguiente manera:

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 del proceso de exportación de telemetría que se describe a continuación.

credenciales

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

muestreador

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

Hay cuatro samplers 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 registros y seguimientos.

disableTraces

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

disableLoggingInputAndOutput

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 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 trazas de Google Cloud para ver la telemetría.

Paquete de Google Cloud Observability

Una vez que se implemente tu código (p.ej., flujo), navega al panel de Cloud Monitoring y selecciona tu proyecto. Desde allí, puedes navegar fácilmente entre los exploradores de registros, métricas y seguimientos para la supervisión de producción.

Registros y seguimientos

En el menú de la izquierda, haz clic en “Explorador de registros” en el encabezado “Explorar”.

Aquí, verás todos los registros asociados con el código de Genkit implementado, incluido console.log(). Cualquier registro que tenga el prefijo [genkit] es un registro interno de Genkit que contiene información que puede ser interesante para fines de depuración. Por ejemplo, los registros de Genkit en el formato Config[...] contienen metadatos, como la temperatura y los valores topK para inferencias específicas de LLM. Los registros en el formato Output[...] contienen respuestas de LLM, mientras que los registros Input[...] contienen las instrucciones. Cloud Logging tiene LCAs sólidas que permiten un control detallado sobre el acceso a los registros sensibles.

Se abrirá un panel de vista previa del seguimiento en el que se mostrarán rápidamente los detalles del seguimiento. Para ver los detalles completos, haz clic en el vínculo “Ver en Trace” en la parte superior derecha del panel.

El elemento de navegación más destacado en Cloud Trace es el diagrama de dispersión de seguimiento. Contiene todos los seguimientos recopilados en un período determinado.

Si haces clic en cada punto de datos, se mostrarán sus detalles debajo del diagrama de dispersión.

La vista detallada contiene la forma del flujo, incluidos todos los pasos, además de información importante sobre el tiempo. Cloud Trace tiene la capacidad de intercalar todos los registros asociados con un seguimiento determinado dentro de esta vista. Selecciona la opción "Mostrar elementos expandidos" en el menú desplegable "Registros y eventos".

La vista resultante permite un examen detallado de los registros en el contexto del seguimiento, incluidas las instrucciones y las respuestas del LLM.

Métricas

Para ver todas las métricas que exporta Genkit, haz clic en “Administración de métricas” en el encabezado “Configurar” del menú de la izquierda.

La consola de administración de métricas contiene una vista tabular de todas las métricas recopiladas, incluidas las que pertenecen a Cloud Run y su entorno. Si haces clic en la opción “Carga de trabajo”, se mostrará una lista que incluye las métricas recopiladas por Genkit. Cualquier métrica con el prefijo genkit constituye una métrica interna de Genkit.

Genkit recopila varias categorías de métricas, como funciones, acciones y generación. Cada métrica tiene varias dimensiones útiles que facilitan un filtrado y un agrupamiento sólidos.

Entre las dimensiones comunes, se incluyen las siguientes:

  • flow_name: El nombre de nivel superior del flujo.
  • flow_path: El intervalo y su cadena superior hasta el intervalo raíz.
  • error_code: En caso de un error, el código de error correspondiente.
  • error_message: En caso de un error, el mensaje de error correspondiente.
  • model: El nombre del modelo.

Métricas de atributos

Las funciones son el punto de entrada de nivel superior a tu código de Genkit. En la mayoría de los casos, será un flujo. De lo contrario, este será el intervalo más alto en un seguimiento.

Nombre Tipo Descripción
genkit/feature/requests Contador Cantidad de solicitudes
genkit/feature/latency Histograma Latencia de ejecución en ms

Cada métrica de componentes contiene las siguientes dimensiones:

Nombre Descripción
nombre Es el nombre de la función. En la mayoría de los casos, este es el flujo de Genkit de nivel superior.
estado "success" o "failure", según si la solicitud de función se realizó correctamente o no
error Solo se establece cuando status=failure. Contiene el tipo de error que causó la falla.
source Es el idioma de origen de Genkit. P. ej., 'ts'
sourceVersion La versión del framework de Genkit

Métricas de acción

Las acciones representan un paso genérico de ejecución dentro de Genkit. Se hará un seguimiento de las siguientes métricas en cada uno de estos pasos:

Nombre Tipo Descripción
genkit/action/requests Contador Cantidad de veces que se ejecutó esta acción
genkit/action/latency Histograma Latencia de ejecución en ms

Cada métrica de acción contiene las siguientes dimensiones:

Nombre Descripción
nombre Es el nombre de la acción.
featureName Es el nombre de la función superior que se está ejecutando.
path Es la ruta de ejecución desde la raíz de la función hasta esta acción. p. ej., '/myFeature/parentAction/thisAction'
estado "success" o "failure", según si la acción se realizó correctamente o no
error Solo se establece cuando status=failure. Contiene el tipo de error que causó la falla.
source Es el idioma de origen de Genkit. P. ej., 'ts'
sourceVersion La versión del framework de Genkit

Genera métricas

Estas son métricas de acciones especiales relacionadas con acciones que interactúan con un modelo. Además de las solicitudes y la latencia, también se realiza un seguimiento de las entradas y salidas, con dimensiones específicas del modelo que facilitan la depuración y el ajuste de la configuración.

Nombre Tipo Descripción
genkit/ai/generate/requests Contador Cantidad de veces que se llamó a este modelo
genkit/ai/generate/latency Histograma Latencia de ejecución en ms
genkit/ai/generate/input/tokens Contador Tokens de entrada
genkit/ai/generate/output/tokens Contador Tokens de salida
genkit/ai/generate/input/characters Contador Caracteres de entrada
genkit/ai/generate/output/characters Contador Caracteres de salida
genkit/ai/generate/input/images Contador Imágenes de entrada
genkit/ai/generate/output/images Contador Imágenes de salida
genkit/ai/generate/input/audio Contador Cómo ingresar archivos de audio
genkit/ai/generate/output/audio Contador Archivos de audio de salida

Cada métrica de generación contiene las siguientes dimensiones:

Nombre Descripción
modelName El nombre del modelo
featureName Es el nombre de la función superior que se está ejecutando.
path Es la ruta de ejecución desde la raíz de la función hasta esta acción. p. ej., '/myFeature/parentAction/thisAction'
latencyMs El tiempo de respuesta que tarda el modelo
estado "success" o "failure", según si la solicitud de función se realizó correctamente o no
error Solo se establece cuando status=failure. Contiene el tipo de error que causó la falla.
source Es el idioma de origen de Genkit. P. ej., 'ts'
sourceVersion La versión del framework de Genkit

Puedes visualizar métricas a través del Explorador de métricas. En el menú lateral izquierdo, haz clic en "Explorador de métricas" en el encabezado "Explorar".

Haz clic en el menú desplegable "Seleccionar una métrica", selecciona "Nodo genérico", "Genkit" y una métrica.

La visualización de la métrica dependerá de su tipo (contador, histograma, etc.). El Explorador de métricas proporciona servicios sólidos de agregación y consulta para ayudar a graficar las métricas según sus distintas dimensiones.

Demora de telemetría

Puede haber una leve demora antes de que la telemetría de una ejecución particular de un flujo se muestre en Cloud's operations suite. En la mayoría de los casos, esta demora es inferior a 1 minuto.

Cuotas y límites

Es importante tener en cuenta varias cuotas:

Costo

Cloud Logging, Cloud Trace y Cloud Monitoring tienen niveles gratuitos generosos. Puedes encontrar los precios específicos en los siguientes vínculos: