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

Instalación

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

Si quieres ejecutar localmente flujos que usan este complemento, también necesitas el 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, agrega el complemento googleCloud a tu configuración de Genkit:

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

export default configureGenkit({
  plugins: [googleCloud()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'googleCloud',
    logger: 'googleCloud',
  },
});

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

Authentication

El complemento requiere el ID del proyecto de Google Cloud 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 configuran automáticamente.

Credencial predeterminada de la aplicación

Para ejecutar en otros entornos, debes 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 de Credenciales predeterminadas de la aplicación.

Credenciales de la cuenta de servicio

Si usas una cuenta de servicio y ejecutas fuera de un entorno de Google Cloud, puedes configurar tus credenciales como una variable de entorno. Sigue estas instrucciones para configurar tu clave de cuenta de servicio de Google Cloud.

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

Ruta de acceso al archivo:

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

Copia directa:

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

El complemento googleCloud() toma un objeto de configuración opcional:

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

ID de proyecto

Esta opción permite especificar de forma explícita el ID del proyecto de Google Cloud. En la mayoría de los casos, esto no es necesario.

Configuración de telemetría

Esta opción configura la instancia del NodeSDK de OpenTelemetry.

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

googleCloud({
  telemetryConfig: {
    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,
  },
});

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).

muestra

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

Existen cuatro muestras preconfiguradas:

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.

metricsExportInterval

Este campo especifica el intervalo de exportación de métricas en milisegundos.

Prueba tu integración

Cuando configures el complemento, usa forceDevExport: true para habilitar la exportación de telemetría para ejecuciones locales. Esta es una forma rápida de enviar tus primeros eventos para su supervisión en Google Cloud.

Supervisión de la producción mediante Google Cloud's operations suite

Una vez que se implemente un flujo, navega a Google Cloud's operations suite y selecciona tu proyecto.

Registros y seguimientos

En el menú lateral, busca “Logging” y haz clic en “Explorador de registros”.

Verás todos los registros asociados con el flujo 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 los registros sensibles.

Para líneas de registro específicas, es posible navegar a sus respectivos seguimientos haciendo clic en el ícono del menú ampliado y seleccionando “Ver detalles de seguimiento”.

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 botón “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 casilla de verificación "Mostrar elementos expandidos" en la sección "Registros y eventos" del menú desplegable.

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 se pueden exportar de Genkit, selecciona "Logging" en el menú lateral y haz clic en “Administración de métricas”.

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 “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, incluidas las métricas a nivel de flujo, de acción y de 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.
  • temperature: El valor de la temperatura de inferencia.
  • topK: El valor topK de inferencia.
  • topP: El valor topP de la inferencia.

Métricas a nivel de flujo

Nombre Dimensiones
genkit/flow/requests flow_name, error_code, error_message
genkit/flow/latency flow_name

Métricas a nivel de la acción

Nombre Dimensiones
genkit/action/requests flow_name, error_code, error_message
genkit/action/latency flow_name

Métricas a nivel de generación

Nombre Dimensiones
genkit/ai/generate flow_path, model, temperature, topK, topP, error_code, error_message
genkit/ai/generate/input_tokens flow_path, model, temperature, topK, topP
genkit/ai/generate/output_tokens flow_path, model, temperature, topK, topP
genkit/ai/generate/input_characters flow_path, model, temperature, topK, topP
genkit/ai/generate/output_characters flow_path, model, temperature, topK, topP
genkit/ai/generate/input_images flow_path, model, temperature, topK, topP
genkit/ai/generate/output_images flow_path, model, temperature, topK, topP
genkit/ai/generate/latency flow_path, model, temperature, topK, topP, error_code, error_message

Puedes visualizar métricas a través del Explorador de métricas. En el menú lateral, selecciona “Logging” y haz clic en "Explorador de métricas"

Haz clic en "Seleccionar una métrica" del menú desplegable, 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 menor 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: