Das Google Cloud-Plug-in exportiert Firebase Genkit-Telemetrie- und Logging-Daten in die Cloud Observability-Suite, die das Firebase AI Monitoring-Dashboard unterstützt.

Installation

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

Wenn Sie Genkit-Code lokal ausführen, der dieses Plug-in enthält, muss auch das Google Cloud CLI-Tool installiert sein.

Google Cloud-Konto einrichten

Für dieses Plug-in ist ein Google Cloud-Konto/-Projekt erforderlich. Alle Firebase-Projekte enthalten standardmäßig einen (GCP Console). Sie können sich auch unter https://cloud.google.com registrieren.

Bevor du das Plug-in hinzufügst, müssen die folgenden APIs für dein GCP-Projekt aktiviert sein:

• Cloud Logging API
• Cloud Trace API
• Cloud Monitoring API

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 Cloud Tracing, Logging und Monitoring (Messwerte) aktivieren möchten, rufen Sie einfach enableGoogleCloudTelemetry() auf:

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

enableGoogleCloudTelemetry();

Bei der Produktion wird die Telemetrie automatisch exportiert.

Authentifizierung und Autorisierung

Das Plug-in benötigt eine Google Cloud-Projekt-ID und Anwendungsanmeldedaten.

Google Cloud

Wenn Sie Ihren Code in einer Google Cloud-Umgebung (z. B. Cloud Functions oder Cloud Run) bereitstellen, werden die Projekt-ID und die Anmeldedaten automatisch über Standardanmeldedaten für Anwendungen ermittelt.

Sie müssen dem Dienstkonto, auf dem Ihr Code ausgeführt wird (d.h. dem „angehängten Dienstkonto“), über die IAM-Konsole die folgenden Rollen zuweisen:

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

Lokale Entwicklung

Bei der lokalen Entwicklung sind zusätzliche Schritte erforderlich, damit Ihre Nutzeranmeldedaten für das Plug-in verfügbar sind.

1. Legen Sie die Umgebungsvariable GCLOUD_PROJECT auf Ihr Google Cloud-Projekt fest.

2. Authentifizieren Sie sich mit der gcloud-Befehlszeile:

   gcloud auth application-default login

Produktionsumgebungen außerhalb von Google Cloud

Nach Möglichkeit sollten Sie jedoch den Prozess für Standardanmeldedaten für Anwendungen verwenden, um Anmeldedaten für das Plug-in verfügbar zu machen.

Normalerweise müssen Sie dazu einen Dienstkontoschlüssel/-paar generieren und diese Anmeldedaten in Ihrer Produktionsumgebung bereitstellen.

1. Folgen Sie der Anleitung zum Einrichten eines Dienstkontoschlüssels.

2. Das Dienstkonto muss die folgenden Rollen haben:

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

3. Stellen Sie die Anmeldedatendatei in der Produktionsumgebung bereit (nicht in den Quellcode einchecken)

4. Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS als Pfad zur Anmeldedatendatei fest.

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

In einigen serverlosen Umgebungen ist es möglicherweise nicht möglich, eine Anmeldedatendatei bereitzustellen. In diesem Fall können Sie alternativ zu den Schritten 3 und 4 oben die Umgebungsvariable GCLOUD_SERVICE_ACCOUNT_CREDS mit dem Inhalt der Anmeldedatendatei so festlegen:

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 enableGoogleCloudTelemetry()-Funktion akzeptiert ein optionales Konfigurationsobjekt, 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:

• AlwaysOnSampler: Alle Traces werden als Stichprobe genommen.
• AlwaysOffSampler – keine Traces werden erfasst
• ParentBased: Stichproben basierend auf der übergeordneten Span
• TraceIdRatioBased: Es wird ein konfigurierbarer Prozentsatz der Traces abgetastet.

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 können Sie den Messwertexport deaktivieren, während weiterhin Protokolle und Traces 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.

Google Cloud Observability-Suite

Nachdem Ihr Code (z.B. der Ablauf) bereitgestellt wurde, rufen Sie das Dashboard Cloud Monitoring auf und wählen Sie Ihr Projekt aus. Von hier aus können Sie ganz einfach zwischen den Explorern „Logs“, „Messwerte“ und „Traces“ wechseln, um die Produktion zu überwachen.

Protokolle und Traces

Klicken Sie im Menü auf der linken Seite unter der Überschrift „Expl. Datenanalyse“ auf „Logs Explorer“.

Hier sehen Sie alle Protokolle, die mit Ihrem bereitgestellten Genkit-Code verknüpft sind, einschließlich console.log(). Alle Protokolle mit dem Präfix [genkit] sind Genkit-interne Protokolle, die Informationen enthalten, die für die Fehlerbehebung interessant sein können. Genkit-Protokolle im Format Config[...] enthalten beispielsweise Metadaten wie die Temperatur und die TopK-Werte für bestimmte LLM-Inferenzen. Protokolle im Format Output[...] enthalten LLM-Antworten, während Input[...]-Protokolle die Prompts enthalten. Cloud Logging bietet robuste ACLs, mit denen sich der Zugriff auf sensible Logs detailliert steuern lässt.

Daraufhin wird ein Vorschaubereich für den Trace geöffnet, in dem Sie einen schnellen Überblick über die Details des Traces erhalten. Klicken Sie rechts oben im Bereich auf den Link „In Trace ansehen“, um alle Details aufzurufen.

Das wichtigste Navigationselement in Cloud Trace ist das Streudiagramm für Traces. Er enthält alle erfassten Traces in einem bestimmten Zeitraum.

Wenn Sie auf einen Datenpunkt klicken, werden die zugehörigen Details unter dem Streudiagramm angezeigt.

Die Detailansicht enthält die Flussform, einschließlich aller Schritte, und wichtige Informationen zum Timing. In Cloud Trace können alle Logs, die mit einem bestimmten Trace verknüpft sind, in dieser Ansicht verschachtelt werden. Wählen Sie im Drop-down-Menü „Protokolle und Ereignisse“ die Option „Maximal maximiert anzeigen“ aus.

In der resultierenden Ansicht können Logs im Kontext des Tracings detailliert geprüft werden, einschließlich Prompts und LLM-Antworten.

Messwerte

Wenn Sie sich alle von Genkit exportierten Messwerte ansehen möchten, klicken Sie links im Menü unter „Konfigurieren“ auf „Messwertverwaltung“.

Die Console zur Verwaltung von Messwerten enthält eine tabellarische Ansicht aller erfassten Messwerte, einschließlich derjenigen, die sich auf Cloud Run und die zugehörigen Umgebungen beziehen. Wenn Sie auf die Option „Workload“ klicken, wird eine Liste mit den von Genkit erfassten Messwerten angezeigt. Alle Messwerte mit dem Präfix genkit sind interne Genkit-Messwerte.

Mit Genkit werden mehrere Messwertkategorien erfasst, darunter „Funktion“, „Aktion“ und „Generieren“. Jeder Messwert hat mehrere nützliche Dimensionen, die eine robuste Filterung und Gruppierung ermöglichen.

Häufig verwendete Dimensionen:

• flow_name: Der Name der obersten Ebene des Ablaufs.
• flow_path – der Span und sein übergeordneter Span werden bis zum Stammspan verkettet.
• error_code: Bei einem Fehler der entsprechende Fehlercode.
• error_message – bei einem Fehler die entsprechende Fehlermeldung.
• model: Der Name des Modells.

Messwerte zu Funktionen

Funktionen sind der Einstiegspunkt auf oberster Ebene in Ihren Genkit-Code. In den meisten Fällen ist dies ein Ablauf. Andernfalls ist dies die oberste Spanne in einem Trace.

Jeder Messwert für Funktionen enthält die folgenden Dimensionen:

Aktionsmesswerte

Aktionen stellen einen generischen Ausführungsschritt in Genkit dar. Für jeden dieser Schritte werden die folgenden Messwerte erfasst:

Jeder Messwert für Aktionen enthält die folgenden Dimensionen:

Messwerte generieren

Das sind spezielle Aktionsmesswerte, die sich auf Aktionen beziehen, die mit einem Modell interagieren. Zusätzlich zu Anfragen und Latenz werden auch Eingabe und Ausgabe erfasst. Dabei werden modellspezifische Dimensionen verwendet, die die Fehlerbehebung und Konfigurationsoptimierung erleichtern.

Jeder generierte Messwert enthält die folgenden Dimensionen:

Messwerte lassen sich im Metrics Explorer visualisieren. Klicken Sie im Menü auf der linken Seite unter der Überschrift „Expl. Datenanalyse“ auf „Metrics Explorer“.

Wählen Sie einen Messwert aus, indem Sie auf das Drop-down-Menü „Messwert auswählen“ klicken, „Generic Node“, „Genkit“ und einen Messwert auswählen.

Die Visualisierung des Messwerts hängt von seinem Typ ab (Zähler, Histogramm usw.). Der Metrics Explorer bietet robuste Aggregations- und Abfragefunktionen, mit denen sich Messwerte nach verschiedenen Dimensionen grafisch darstellen lassen.

Telemetrieverzögerung

Es kann etwas dauern, bis die Telemetriedaten für eine bestimmte Ausführung eines Ablaufs in der Operations Suite von Google Cloud angezeigt werden. In den meisten Fällen dauert es weniger als eine Minute.

Kontingente und Limits

Es gibt mehrere Kontingente, die Sie beachten sollten:

• Cloud Trace-Kontingente
• Kontingente für Cloud Logging
• Kontingente für Cloud Monitoring

Kosten

Cloud Logging, Cloud Trace und Cloud Monitoring sind in großzügigen kostenlosen Stufen verfügbar. Spezifische Preise finden Sie unter den folgenden Links:

• Cloud Logging – Preise
• Cloud Trace-Preise
• Cloud Monitoring-Preise