Plug-in Google Cloud

Le plug-in Google Cloud exporte les données de télémétrie et de journalisation de Firebase Genkit vers la suite Google Cloud Operations, qui alimente le tableau de bord Firebase AI Monitoring (version preview privée).

Installation

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

Si vous souhaitez exécuter localement des flux qui utilisent ce plug-in, vous devez également installer l'outil Google Cloud CLI.

Configurer un compte Google Cloud

Ce plug-in nécessite un compte Google Cloud (inscrivez-vous si vous n'en avez pas encore) et un projet Google Cloud.

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

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 d'API.

Configuration de Genkit

Pour activer l'exportation vers Google Cloud Tracing, Logging et Monitoring, appelez simplement enableGoogleCloudTelemetry():

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

enableGoogleCloudTelemetry();

Lorsque vous exécutez votre application en production, votre télémétrie est automatiquement exportée.

Authentification

Le plug-in nécessite l'ID de projet Google Cloud et les identifiants de votre projet Google Cloud. Si vous exécutez votre flux à partir d'un environnement Google Cloud (Cloud Functions, Cloud Run, etc.), l'ID de projet et les identifiants sont définis automatiquement.

Identifiants par défaut de l'application

Pour exécuter l'application dans d'autres environnements, vous devez définir la variable d'environnement GCLOUD_PROJECT sur votre projet Google Cloud et vous authentifier à l'aide de l'outil gcloud:

gcloud auth application-default login

Pour en savoir plus, consultez la documentation sur les identifiants par défaut de l'application.

Identifiants du compte de service

Si vous utilisez un compte de service et que vous exécutez votre application en dehors d'un environnement Google Cloud, vous pouvez définir vos identifiants en tant que variable d'environnement. Suivez les instructions pour configurer votre clé de compte de service Google Cloud.

Une fois que vous avez téléchargé le fichier de clé, vous pouvez spécifier les identifiants de deux manières : en indiquant un emplacement de fichier à l'aide de la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS ou en copiant directement le contenu du fichier JSON dans la variable d'environnement GCLOUD_SERVICE_ACCOUNT_CREDS.

Chemin d'accès au fichier:

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

Copie directe:

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() utilise un objet de configuration facultatif qui configure l'instance du NodeSDK OpenTelemetry.

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 d'échantillonner les traces.

Il existe quatre échantillons préconfigurés:

autoInstrumentation et autoInstrumentationConfig

L'activation de l'instrumentation automatique permet à OpenTelemetry de capturer des 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.

disableLoggingIO

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 de journaux, de métriques ou de traces Google Cloud pour afficher la télémétrie. Vous pouvez également accéder au tableau de bord Firebase AI Monitoring (Preview privée) pour obtenir une vue de la télémétrie adaptée à l'IA.