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 deseas ejecutar de forma local los flujos que usan este complemento, también necesitas tener instalada la herramienta de 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.

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

Configuración de complementos

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

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

projectId

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.

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 LCA 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 “View in trace details”.

Se abrirá un panel de vista previa del seguimiento en el que se mostrarán rápidamente los detalles del seguimiento. Para obtener los detalles completos, haz clic en el vínculo “View in 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 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, 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 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, 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: Es 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: Es el nombre del modelo.
  • temperature: Es el valor de la temperatura de inferencia.
  • topK: El valor superior de la inferencia.
  • topP: Es el valor de P superior de la inferencia.

Métricas a nivel de flujo

Nombre Dimensiones
genkit/flujo/solicitudes flow_name, error_code, error_message
genkit/flujo/latencia nombre_flujo

Métricas a nivel de la acción

Nombre Dimensiones
genkit/acción/solicitudes flow_name, error_code, error_message
kit de generación/acción/latencia nombre_flujo

Métricas a nivel de generación

Nombre Dimensiones
genkit/ai/generate Flow_path, modelo, temperatura, topK, topP, error_code, error_message
genkit/ai/generate/input_tokens. flujo_ruta, modelo, temperatura, topK, topP
genkit/ai/generate/output_tokens flujo_ruta, modelo, temperatura, topK, topP
genkit/ai/generate/input_characters. flujo_ruta, modelo, temperatura, topK, topP
genkit/ai/generate/output_characters flujo_ruta, modelo, temperatura, topK, topP
genkit/ai/generate/input_images. flujo_ruta, modelo, temperatura, topK, topP
genkit/ai/generate/output_images flujo_ruta, modelo, temperatura, topK, topP
genkit/ai/generate/latencia Flow_path, modelo, temperatura, 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".

Para seleccionar una métrica, 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.

Retraso 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: