Plug-in Google Cloud

Le plug-in Google Cloud exporte les données de télémétrie et de journalisation Firebase Genkit vers la suite Cloud Observability.

Installation

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

Lorsque vous exécutez en local du code Genkit qui inclut ce plug-in, vous devez également installer l'outil Google Cloud CLI.

Configurer un compte Google Cloud

Ce plug-in nécessite un compte/projet Google Cloud. Tous les projets Firebase en incluent un par défaut (Console GCP), ou vous pouvez vous inscrire sur https://cloud.google.com.

Avant d'ajouter le plug-in, assurez-vous que les API suivantes sont activées pour votre projet GCP:

Ces API doivent figurer dans le tableau de bord des API de votre projet.

Cliquez ici pour en savoir plus sur l'activation et la désactivation des API.

Configuration de Genkit

Pour activer le traçage, la journalisation et la surveillance (métriques) dans Cloud, appelez simplement enableGoogleCloudTelemetry():

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

enableGoogleCloudTelemetry();

Lors de l'exécution en production, la télémétrie est exportée automatiquement.

Authentification et autorisation

Le plug-in nécessite un ID de projet Google Cloud et des identifiants d'application.

Google Cloud

Si vous déployez votre code dans un environnement Google Cloud (Cloud Functions, Cloud Run, etc.), l'ID de projet et les identifiants seront découverts automatiquement via les identifiants par défaut de l'application.

Vous devez appliquer les rôles suivants au compte de service qui exécute votre code (c'est-à-dire le "compte de service associé") via la console IAM:

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

Développement local

Lors du développement local, des étapes supplémentaires sont nécessaires pour que vos identifiants utilisateur soient disponibles pour le plug-in.

  1. Définissez la variable d'environnement GCLOUD_PROJECT sur votre projet Google Cloud.

  2. Authentifiez-vous à l'aide de la CLI gcloud:

    gcloud auth application-default login

Environnements de production en dehors de Google Cloud

Si possible, il est toujours recommandé d'utiliser le processus des identifiants par défaut de l'application pour mettre les identifiants à la disposition du plug-in.

En règle générale, cela implique de générer une clé/une paire de clés de compte de service et de déployer ces identifiants dans votre environnement de production.

  1. Suivez les instructions pour configurer une clé de compte de service.

  2. Assurez-vous que le compte de service dispose des rôles suivants:

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

  3. Déployez le fichier d'identifiants en production (ne le vérifiez pas dans le code source).

  4. Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS comme chemin d'accès au fichier d'identifiants.

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

Dans certains environnements sans serveur, vous ne pourrez peut-être pas déployer de fichier d'identifiants. Dans ce cas, au lieu des étapes 3 et 4 ci-dessus, vous pouvez définir la variable d'environnement GCLOUD_SERVICE_ACCOUNT_CREDS avec le contenu du fichier d'identifiants comme suit:

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

Configuration du plug-in

La fonction enableGoogleCloudTelemetry() accepte un objet de configuration facultatif qui configure l'instance du SDK OpenTelemetry Node.js.

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,
});

Les objets de configuration permettent de contrôler précisément différents aspects de l'exportation de la télémétrie, comme indiqué ci-dessous.

credentials

Permet de spécifier des identifiants directement à l'aide de JWTInput à partir de la bibliothèque google-auth.

échantillonneur

Lorsque l'exportation de toutes les traces n'est pas pratique, OpenTelemetry permet l'échantillonnage des traces.

Il existe quatre échantillons préconfigurés:

autoInstrumentation et autoInstrumentationConfig

L'activation de l'instrumentation automatique permet à OpenTelemetry de capturer les données de télémétrie à partir de bibliothèques tierces sans avoir à modifier le code.

metricExportIntervalMillis

Ce champ spécifie l'intervalle d'exportation des métriques en millisecondes.

metricExportTimeoutMillis

Ce champ spécifie le délai avant expiration de l'exportation des métriques, en millisecondes.

disableMetrics

Fournit un forçage qui désactive l'exportation des métriques tout en continuant à exporter les traces et les journaux.

disableTraces

Fournit un forçage qui désactive l'exportation des traces tout en continuant à exporter les métriques et les journaux.

disableLoggingInputAndOutput

Fournit un forçage qui désactive la collecte des journaux d'entrée et de sortie.

forceDevExport

Cette option oblige Genkit à exporter les données de télémétrie et de journalisation lorsqu'il s'exécute dans l'environnement dev (par exemple, localement).

Tester votre intégration

Lorsque vous configurez le plug-in, utilisez forceDevExport: true pour activer l'exportation de la télémétrie pour les exécutions locales. Accédez à l'explorateur Google Cloud Logs, Metrics ou Trace pour afficher la télémétrie.

Suite Google Cloud Observability

Une fois votre code (par exemple, votre flux) déployé, accédez au tableau de bord Cloud Monitoring et sélectionnez votre projet. Vous pouvez ensuite facilement passer de l'explorateur de journaux, des métriques et des traces pour surveiller la production.

Journaux et traces

Dans le menu de gauche, cliquez sur "Explorateur de journaux" sous l'en-tête "Explorer".

Tous les journaux associés à votre code Genkit déployé s'affichent ici, y compris console.log(). Tout journal portant le préfixe [genkit] est un journal interne à Genkit qui contient des informations pouvant être intéressantes à des fins de débogage. Par exemple, les journaux Genkit au format Config[...] contiennent des métadonnées telles que la température et les valeurs topK pour des inférences LLM spécifiques. Les journaux au format Output[...] contiennent les réponses du LLM, tandis que les journaux Input[...] contiennent les requêtes. Cloud Logging dispose de LCA robustes qui permettent de contrôler précisément l'accès aux journaux sensibles.

Un volet d'aperçu de la trace s'affiche, offrant un aperçu rapide des détails de la trace. Pour obtenir tous les détails, cliquez sur le lien "Afficher dans la trace" en haut à droite du volet.

L'élément de navigation le plus important de Cloud Trace est le nuage de points des traces. Il contient toutes les traces collectées sur une période donnée.

Cliquez sur chaque point de données pour afficher ses détails sous le nuage de points.

La vue détaillée contient la forme du flux, y compris toutes les étapes, ainsi que des informations temporelles importantes. Cloud Trace peut intercaler tous les journaux associés à une trace donnée dans cette vue. Sélectionnez l'option"Afficher développé " dans le menu déroulant "Journaux et événements".

La vue obtenue permet d'examiner en détail les journaux dans le contexte de la trace, y compris les invites et les réponses du LLM.

Métriques

Pour afficher toutes les métriques exportées par Genkit, cliquez sur "Gestion des métriques" sous l'en-tête "Configurer" dans le menu de gauche.

La console de gestion des métriques contient une vue tabulaire de toutes les métriques collectées, y compris celles qui concernent Cloud Run et son environnement. Cliquez sur l'option "Charge de travail" pour afficher une liste incluant les métriques collectées par Genkit. Toute métrique avec le préfixe genkit constitue une métrique Genkit interne.

Genkit collecte plusieurs catégories de métriques, y compris les métriques de fonctionnalité, d'action et de génération. Chaque métrique comporte plusieurs dimensions utiles qui facilitent le filtrage et le regroupement efficaces.

Voici quelques dimensions courantes:

  • flow_name : nom de premier niveau du flux.
  • flow_path : le segment et son segment parent se chevauchent jusqu'au segment racine.
  • error_code : en cas d'erreur, code d'erreur correspondant.
  • error_message : en cas d'erreur, message d'erreur correspondant.
  • model : nom du modèle.

Métriques des fonctionnalités

Les fonctionnalités sont le point d'entrée de premier niveau de votre code Genkit. Dans la plupart des cas, il s'agit d'un flux. Sinon, il s'agit de la partie supérieure d'une trace.

Nom Type Description
genkit/feature/requests Compteur Nombre de requêtes
genkit/feature/latency Histogramme Latence d'exécution en ms

Chaque métrique d'éléments géographiques contient les dimensions suivantes:

Nom Description
nom Nom de la fonctionnalité. Dans la plupart des cas, il s'agit du flux Genkit de premier niveau.
état "success" ou "failure", selon que la demande de fonctionnalité a réussi ou non
erreur Défini uniquement lorsque status=failure. Indique le type d'erreur à l'origine de l'échec
source Langue source de Genkit. Par exemple, 'ts'
sourceVersion Version du framework Genkit

Métriques d'action

Les actions représentent une étape d'exécution générique dans Genkit. Les métriques suivantes seront suivies pour chacune de ces étapes:

Nom Type Description
genkit/action/requests Compteur Nombre de fois où cette action a été exécutée
genkit/action/latency Histogramme Latence d'exécution en ms

Chaque métrique d'action contient les dimensions suivantes:

Nom Description
nom Nom de l'action
featureName Nom de la fonctionnalité parente en cours d'exécution
chemin d'accès Chemin d'exécution depuis la racine de l'élément géographique jusqu'à cette action. Exemple : '/myFeature/parentAction/thisAction'
état "success" ou "failure", selon que l'action a réussi ou non
erreur Défini uniquement lorsque status=failure. Indique le type d'erreur à l'origine de l'échec
source Langue source de Genkit. Par exemple, 'ts'
sourceVersion Version du framework Genkit

Générer des métriques

Il s'agit de métriques d'action spéciales liées aux actions qui interagissent avec un modèle. En plus des requêtes et de la latence, les entrées et les sorties sont également suivies, avec des dimensions spécifiques au modèle qui facilitent le débogage et le réglage de la configuration.

Nom Type Description
genkit/ai/generate/requests Compteur Nombre de fois où ce modèle a été appelé
genkit/ai/generate/latency Histogramme Latence d'exécution en ms
genkit/ai/generate/input/tokens Compteur Jetons d'entrée
genkit/ai/generate/output/tokens Compteur Jetons de sortie
genkit/ai/generate/input/characters Compteur Caractères d'entrée
genkit/ai/generate/output/characters Compteur Caractères de sortie
genkit/ai/generate/input/images Compteur Images d'entrée
genkit/ai/generate/output/images Compteur Images de sortie
genkit/ai/generate/input/audio Compteur Fichiers audio d'entrée
genkit/ai/generate/output/audio Compteur Fichiers audio de sortie

Chaque métrique de génération contient les dimensions suivantes:

Nom Description
modelName Nom du modèle
featureName Nom de la fonctionnalité parente en cours d'exécution
chemin d'accès Chemin d'exécution depuis la racine de l'élément géographique jusqu'à cette action. Exemple : '/myFeature/parentAction/thisAction'
latencyMs Temps de réponse du modèle
état "success" ou "failure", selon que la demande de fonctionnalité a réussi ou non
erreur Défini uniquement lorsque status=failure. Indique le type d'erreur à l'origine de l'échec
source Langue source de Genkit. Par exemple, 'ts'
sourceVersion Version du framework Genkit

Vous pouvez visualiser les métriques dans l'explorateur de métriques. Dans le menu de gauche, cliquez sur "Explorateur de métriques" sous l'en-tête "Explorer".

Sélectionnez une métrique en cliquant sur le menu déroulant "Sélectionner une métrique", puis sélectionnez "Nœud générique", "Genkit" et une métrique.

La visualisation de la métrique dépend de son type (compteur, histogramme, etc.). L'explorateur de métriques fournit des fonctionnalités d'agrégation et de requête robustes pour vous aider à représenter graphiquement les métriques en fonction de leurs différentes dimensions.

Délai de télémétrie

Un léger délai peut s'écouler avant que la télémétrie d'une exécution particulière d'un flux ne s'affiche dans la suite d'opérations de Cloud. Dans la plupart des cas, ce délai est inférieur à une minute.

Quotas et limites

Plusieurs quotas sont importants à prendre en compte:

Coût

Cloud Logging, Cloud Trace et Cloud Monitoring proposent des niveaux sans frais généreux. Vous trouverez les tarifs spécifiques sur les liens suivants: