Google Cloud-Plug-in

Das Google Cloud-Plug-in exportiert die Telemetrie- und Logging-Daten von Firebase Genkit in die Operations-Suite von Google Cloud, die das Dashboard für Firebase AI Monitoring (private Vorabversion) unterstützt.

Installation

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

Wenn Sie Workflows, die dieses Plug-in verwenden, lokal ausführen möchten, muss außerdem das Google Cloud CLI-Tool installiert sein.

Google Cloud-Konto einrichten

Für dieses Plug-in ist ein Google Cloud-Konto (registrieren Sie sich, falls Sie noch keines haben) und ein Google Cloud-Projekt erforderlich.

Bevor Sie das Plug-in hinzufügen, müssen die folgenden APIs für Ihr Projekt aktiviert sein:

Diese APIs sollten im API-Dashboard für Ihr Projekt aufgeführt sein.

Weitere Informationen zum Aktivieren und Deaktivieren von APIs

Genkit-Konfiguration

Wenn Sie den Export in Google Cloud Tracing, Logging und Monitoring aktivieren möchten, rufen Sie einfach enableGoogleCloudTelemetry() auf:

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

enableGoogleCloudTelemetry();

Wenn Sie die App in der Produktion ausführen, werden Ihre Telemetriedaten automatisch exportiert.

Authentifizierung

Das Plug-in benötigt die Google Cloud-Projekt-ID und die Anmeldedaten für Ihr Google Cloud-Projekt. Wenn Sie den Ablauf in einer Google Cloud-Umgebung (z. B. Cloud Functions oder Cloud Run) ausführen, werden die Projekt-ID und die Anmeldedaten automatisch festgelegt.

Standardanmeldedaten für Anwendungen

Wenn Sie das Tool in anderen Umgebungen ausführen möchten, müssen Sie die Umgebungsvariable GCLOUD_PROJECT auf Ihr Google Cloud-Projekt festlegen und sich mit dem gcloud-Tool authentifizieren:

gcloud auth application-default login

Weitere Informationen finden Sie in der Dokumentation zu Standardanmeldedaten für Anwendungen.

Dienstkonto-Anmeldedaten

Wenn Sie ein Dienstkonto verwenden und die Anwendung außerhalb einer Google Cloud-Umgebung ausführen, können Sie Ihre Anmeldedaten als Umgebungsvariable festlegen. Folgen Sie dieser Anleitung, um Ihren Google Cloud-Dienstkontoschlüssel einzurichten.

Nachdem Sie die Schlüsseldatei heruntergeladen haben, können Sie die Anmeldedaten auf zwei Arten angeben: über die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS oder indem Sie den Inhalt der JSON-Datei direkt in die Umgebungsvariable GCLOUD_SERVICE_ACCOUNT_CREDS kopieren.

Dateipfad:

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

Direkter Text:

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

Plug‑in-Konfiguration

Die Funktion enableGoogleCloudTelemetry() nimmt ein optionales Konfigurationsobjekt an, mit dem die Instanz des OpenTelemetry NodeSDK konfiguriert wird.

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

Mit den Konfigurationsobjekten können Sie verschiedene Aspekte des Telemetrieexports (siehe unten) detailliert steuern.

Anmeldedaten

Ermöglicht die direkte Angabe von Anmeldedaten mit JWTInput aus der google-auth-Bibliothek.

Sampler

Wenn der Export aller Traces nicht praktikabel ist, ermöglicht OpenTelemetry die Stichprobenerhebung von Traces.

Es gibt vier vorkonfigurierte Sampler:

autoInstrumentation und autoInstrumentationConfig

Wenn Sie die automatische Instrumentierung aktivieren, kann OpenTelemetry Telemetriedaten aus Bibliotheken von Drittanbietern erfassen, ohne dass Code geändert werden muss.

metricExportIntervalMillis

In diesem Feld wird das Intervall für den Messwertexport in Millisekunden angegeben.

metricExportTimeoutMillis

In diesem Feld wird das Zeitlimit für den Messwertexport in Millisekunden angegeben.

disableMetrics

Hiermit wird der Export von Messwerten deaktiviert, während Traces und Logs weiterhin exportiert werden.

disableTraces

Hiermit wird der Export von Traces deaktiviert, während Messwerte und Protokolle weiterhin exportiert werden.

disableLoggingIO

Überschreibung, mit der das Erfassen von Eingabe- und Ausgabeprotokollen deaktiviert wird.

forceDevExport

Mit dieser Option wird Genkit gezwungen, Telemetrie- und Protokolldaten zu exportieren, wenn es in der dev-Umgebung ausgeführt wird (z.B. lokal).

Integration testen

Aktivieren Sie beim Konfigurieren des Plug-ins mit forceDevExport: true den Telemetrieexport für lokale Ausführungen. Rufen Sie den Google Cloud Logs Explorer, den Metrics Explorer oder den Trace Explorer auf, um sich die Telemetriedaten anzusehen. Alternativ können Sie das Firebase AI Monitoring-Dashboard (private Vorschau) aufrufen, um eine KI-spezifische Ansicht der Telemetrie zu erhalten.