Plug-in Google Cloud

Il plug-in Google Cloud esporta i dati di telemetria e logging di Firebase Genkit nella suite operativa di Google Cloud, che alimenta la dashboard di Firebase AI Monitoring (anteprima privata).

Installazione

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

Se vuoi eseguire localmente i flussi che utilizzano questo plug-in, devi anche installare lo strumento Google Cloud CLI.

Configurare un account Google Cloud

Questo plug-in richiede un account Google Cloud (registrati se non ne hai già uno) e un progetto Google Cloud.

Prima di aggiungere il plug-in, assicurati che le seguenti API siano abilitate per il tuo progetto:

Queste API dovrebbero essere elencate nella dashboard delle API del progetto.

Fai clic qui per scoprire di più sull'attivazione e la disattivazione delle API.

Configurazione di Genkit

Per attivare l'esportazione in Tracing, Logging e Monitoring di Google Cloud, chiama semplicemente enableGoogleCloudTelemetry():

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

enableGoogleCloudTelemetry();

Quando viene eseguita in produzione, la telemetria viene esportata automaticamente.

Autenticazione

Il plug-in richiede l'ID progetto Google Cloud e le credenziali del progetto Google Cloud. Se esegui il flusso da un ambiente Google Cloud (Cloud Functions, Cloud Run e così via), l'ID progetto e le credenziali vengono impostati automaticamente.

Credenziali predefinite dell'applicazione

L'esecuzione in altri ambienti richiede l'impostazione della variabile di ambiente GCLOUD_PROJECT nel progetto Google Cloud e l'autenticazione utilizzando lo strumento gcloud:

gcloud auth application-default login

Per ulteriori informazioni, consulta la documentazione relativa alle credenziali predefinite dell'applicazione.

Credenziali dell'account di servizio

Se utilizzi un account di servizio e esegui l'operazione al di fuori di un ambiente Google Cloud, puoi impostare le tue credenziali come variabile di ambiente. Segui le istruzioni riportate qui per configurare la chiave dell'account di servizio Google Cloud.

Dopo aver scaricato il file della chiave, puoi specificare le credenziali in due modi: un percorso file utilizzando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS o copiando direttamente i contenuti del file JSON nella variabile di ambiente GCLOUD_SERVICE_ACCOUNT_CREDS.

Percorso del file:

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

Testo diretto:

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

Configurazione plug-in

La funzione enableGoogleCloudTelemetry() accetta un oggetto di configurazione facoltativo che configura l'istanza OpenTelemetry NodeSDK.

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

Gli oggetti di configurazione consentono un controllo granulare su vari aspetti dell'esportazione della telemetria descritti di seguito.

le credenziali

Consente di specificare le credenziali direttamente utilizzando JWTInput dalla libreria google-auth.

campionatore

Nei casi in cui l'esportazione di tutte le tracce non sia praticabile, OpenTelemetry consente il campionamento delle tracce.

Esistono quattro sampler preconfigurati:

autoInstrumentation e autoInstrumentationConfig

L'attivazione della strumentazione automatica consente a OpenTelemetry di acquisire i dati di telemetria dalle librerie di terze parti senza dover modificare il codice.

metricExportIntervalMillis

Questo campo specifica l'intervallo di esportazione delle metriche in millisecondi.

metricExportTimeoutMillis

Questo campo specifica il timeout per l'esportazione delle metriche in millisecondi.

disableMetrics

Fornisce un'override che disattiva l'esportazione delle metriche, continuando a esportare tracce e log.

disattivaTraces

Fornisce un'override che disattiva l'esportazione delle tracce, continuando a esportare metriche e log.

disableLoggingIO

Fornisce un'override che disattiva la raccolta dei log di input e output.

forceDevExport

Questa opzione forza Genkit a esportare i dati di telemetria e log quando viene eseguito nell'ambiente dev (ad es. localmente).

Testa l'integrazione

Quando configuri il plug-in, utilizza forceDevExport: true per attivare l'esportazione della telemetria per le esecuzioni locali. Vai a Logging, Metrics o Trace Explorer di Google Cloud per visualizzare la telemetria. In alternativa, vai alla dashboard di Firebase AI Monitoring (anteprima privata) per una visualizzazione della telemetria incentrata sull'IA.