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 flujos de forma local 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 aparecer en el panel de APIs de tu proyecto.

Haz clic aquí para obtener más información sobre cómo inhabilitar y habilitar las 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, la 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. La ejecución en otros entornos requiere configurar la variable de entorno GCLOUD_PROJECT en tu proyecto de Google Cloud y autenticar 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,
    forceDevExport?: boolean,
    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.

forzarDevExport

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

configuración de telemetría

Esta opción configura la instancia NodeSDK de OpenTelemetry.

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

googleCloud({
  forceDevExport: false, // Set this to true to export telemetry for local runs
  telemetryConfig: {
    sampler: new AlwaysOnSampler(),
    autoInstrumentation: true,
    autoInstrumentationConfig: {
      '@opentelemetry/instrumentation-fs': { enabled: false },
      '@opentelemetry/instrumentation-dns': { enabled: false },
      '@opentelemetry/instrumentation-net': { enabled: false },
    },
    metricExportIntervalMillis: 5_000,
  },
});

muestra

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

Hay 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 producción a través de 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 los mensajes. Cloud Logging cuenta con LCA sólidas que permiten un control detallado sobre los registros sensibles.

En el caso de líneas de registro específicas, es posible navegar a sus seguimientos respectivos haciendo clic en el ícono del menú ampliado y seleccionando "View in trace details" (Ver en detalles de seguimiento).

Esto abrirá un panel de vista previa del seguimiento que proporciona una vista rápida de los detalles del seguimiento. Para obtener todos los detalles, haz clic en el vínculo “Ver en seguimiento” en la parte superior derecha del panel.

El elemento de navegación más importante 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 dato, se mostrarán sus detalles debajo del diagrama de dispersión.

La vista detallada contiene la forma del flujo, incluidos todos los pasos y la 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 expandido" en el menú desplegable "Registros y eventos".

La vista resultante permite examinar en detalle los registros en el contexto del seguimiento, incluidos los mensajes y las respuestas del LLM.

Métricas

Ver todas las métricas que exporta Genkit se pueden hacer seleccionando “Logging” en el menú lateral y haciendo 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 relacionadas con Cloud Run y su entorno. Si haces clic en la opción “Carga de trabajo”, verás una lista con 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 de nivel de flujo, de acción y de nivel de generación. Cada métrica tiene varias dimensiones útiles que facilitan el filtrado y el 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 intervalo superior se encadenan hasta el intervalo raíz.
  • error_code: En caso de error, el código de error correspondiente
  • error_message: En caso de error, el mensaje de error correspondiente
  • model: Es el nombre del modelo.
  • temperature: El valor de la temperatura de inferencia.
  • topK: Es el valor de TopK de inferencia.
  • topP: Es el valor superior de la inferencia.

Métricas de nivel de flujo

Nombre Dimensiones
genkit/flujo/solicitudes nombre_flujo, código_error, mensaje_error
genkit/flujo/latencia nombre_flujo

Métricas a nivel de la acción

Nombre Dimensiones
genkit/acción/solicitudes nombre_flujo, código_error, mensaje_error
genkit/acción/latencia nombre_flujo

Métricas a nivel de generación

Nombre Dimensiones
genkit/IA/generar flujo_ruta, modelo, temperatura, topK, topP, código_de_error, mensaje_de_error
genkit/ai/generate/input_tokens ruta_flujo, modelo, temperatura, topK, topP
genkit/ai/generate/output_tokens ruta_flujo, modelo, temperatura, topK, topP
genkit/ai/generate/input_characters ruta_flujo, modelo, temperatura, topK, topP
genkit/ai/generate/output_characters ruta_flujo, modelo, temperatura, topK, topP
genkit/ai/generate/input_images ruta_flujo, modelo, temperatura, topK, topP
genkit/ai/generate/output_images ruta_flujo, modelo, temperatura, topK, topP
genkit/IA/generar/latencia flujo_ruta, modelo, temperatura, topK, topP, código_de_error, mensaje_de_error

La visualización de métricas se puede hacer 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 el menú desplegable “Seleccionar una métrica” para elegir 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 recursos sólidos de agregación y consulta para ayudar a graficar las métricas según sus diversas dimensiones.

Retraso de telemetría

Es posible que haya una pequeña demora antes de que se muestre la telemetría de una ejecución particular de un flujo 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: