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.

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 sind ein Google Cloud-Konto und ein Google Cloud-Projekt erforderlich. Wenn Sie noch keines haben, registrieren Sie sich hier.

Prüfen Sie vor dem Hinzufügen des Plug-ins, ob die folgenden APIs für Ihr Projekt aktiviert sind:

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 nach Google Cloud Tracing, Logging und Monitoring aktivieren möchten, fügen Sie Ihrer Genkit-Konfiguration das Plug-in googleCloud hinzu:

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

export default configureGenkit({
  plugins: [googleCloud()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'googleCloud',
    logger: 'googleCloud',
  },
});

Bei der Ausführung in der Produktion wird Ihre Telemetrie automatisch exportiert.

Authentifizierung

Für das Plug-in sind die Google Cloud-Projekt-ID und die Anmeldedaten Ihres Google Cloud-Projekts erforderlich. Wenn Sie Ihren Ablauf in einer Google Cloud-Umgebung (Cloud Functions, Cloud Run usw.) 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 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 als Dateispeicherort angeben. Verwenden Sie dazu die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS oder kopieren Sie den Inhalt der JSON-Datei direkt in die Umgebungsvariable GCLOUD_SERVICE_ACCOUNT_CREDS.

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

Das Plug-in googleCloud() verwendet ein optionales Konfigurationsobjekt:

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

projectId

Mit dieser Option können Sie die Google Cloud-Projekt-ID explizit angeben. In den meisten Fällen ist das nicht erforderlich.

telemetryConfig

Mit dieser Option wird die OpenTelemetry NodeSDK-Instanz konfiguriert.

import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';

googleCloud({
  telemetryConfig: {
    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,
  },
});

Export-Entwicklung erzwingen

Mit dieser Option wird Genkit gezwungen, Telemetrie- und Protokolldaten bei der Ausführung in der dev-Umgebung (z.B. lokal) zu exportieren.

Sampler

Wenn der Export aller Traces nicht praktikabel ist, lässt OpenTelemetry das Sampling von Traces zu.

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.

MetricsExportInterval

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

Integration testen

Verwenden Sie beim Konfigurieren des Plug-ins forceDevExport: true, um den Telemetrieexport für lokale Ausführungen zu aktivieren. So können Sie schnell Ihre ersten Ereignisse zum Überwachen in Google Cloud senden.

Produktionsüberwachung über die Operations Suite von Google Cloud

Rufen Sie nach der Bereitstellung eines Ablaufs die Operations-Suite von Google Cloud auf und wählen Sie Ihr Projekt aus.

Protokolle und Traces

Klicken Sie im seitlichen Menü auf „Logging“ und dann auf „Log-Explorer“.

Sie sehen alle Protokolle, die mit Ihrem bereitgestellten Ablauf verknüpft sind, einschließlich console.log(). Jedes Log mit dem Präfix [genkit] ist ein Genkit-internes Log mit Informationen, die für die Fehlerbehebung interessant sein könnten. Genkit-Logs im Format Config[...] enthalten beispielsweise Metadaten wie die Temperatur- und TopK-Werte für bestimmte LLM-Inferenzen. Protokolle im Format Output[...] enthalten LLM-Antworten, während Input[...]-Protokolle die Prompts enthalten. Cloud Logging verfügt über robuste ACLs, die eine detaillierte Kontrolle über sensible Logs ermöglichen.

Für bestimmte Logzeilen können Sie die entsprechenden Traces aufrufen, indem Sie auf das Dreipunkt-Menü  klicken und „In Trace-Details ansehen“ auswählen.

Daraufhin wird eine Trace-Vorschau mit einem kurzen Blick auf die Details des Trace geöffnet. Um alle Details zu sehen, klicken Sie auf „In Trace ansehen“ oben rechts im Fenster.

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

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

Die Detailansicht enthält die Flussform einschließlich aller Schritte und wichtiger Zeitinformationen. Cloud Trace kann alle Logs, die mit einem bestimmten Trace verknüpft sind, in dieser Ansicht verschachteln. Wählen Sie im Drop-down-Menü „Protokolle und Ereignisse“ die Option „Maximal maximiert anzeigen“ aus.

Die resultierende Ansicht ermöglicht eine detaillierte Untersuchung von Logs im Kontext des Trace, einschließlich Aufforderungen und LLM-Antworten.

Messwerte

Wenn Sie „Logging“ auswählen, können Sie sich alle Messwerte ansehen, die von Genkit-Exporten exportiert werden können. im seitlichen Menü 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. Durch Klicken auf „Arbeitslast“ wird eine Liste mit von Genkit erfassten Messwerten eingeblendet. Jeder Messwert mit dem Präfix genkit stellt einen internen Genkit-Messwert dar.

Genkit erfasst mehrere Kategorien von Messwerten, darunter Messwerte auf Fluss-, Aktionsebene und Generierungsebene. Jeder Messwert verfügt über mehrere nützliche Dimensionen, die eine zuverlässige Filterung und Gruppierung ermöglichen.

Gängige Dimensionen:

  • flow_name: Der Name der obersten Ebene des Ablaufs.
  • flow_path – der Span und sein übergeordnetes Span sind bis zum Stamm-Span verkettet.
  • error_code: Im Fall eines Fehlers der entsprechende Fehlercode.
  • error_message – bei einem Fehler die entsprechende Fehlermeldung.
  • model: Der Name des Modells.
  • temperature – der Wert der Inferenztemperatur.
  • topK: Der Wert für die Top-K-Inferenz.
  • topP: Der Wert für die Inferenz-TopP.

Messwerte auf Ablaufebene

Name Dimensionen
Genkit/Ablauf/Anfragen Flowname, Fehlercode, Fehlermeldung
genkit/flow/latency flow_name

Messwerte auf Aktionsebene

Name Dimensionen
Genkit/Aktion/Anfragen Flowname, Fehlercode, Fehlermeldung
genkit/action/latency Flow_name

Messwerte auf Generierebene

Name Dimensionen
genkit/ai/generate Flusspfad, Modell, Temperatur, TopK, TopP, Fehlercode, Fehlermeldung
Genkit/AI/generate/input_tokens flow_path, model, temperature, topK, topP
genkit/ai/generate/output_tokens flow_path, model, temperature, topK, topP
genkit/ai/generate/input_characters flow_path, model, temperature, topK, topP
Genkit/ai/generate/output_characters Flow_path, Modell, Temperatur, TopK, TopP
genkit/ai/generate/input_images flow_path, model, temperature, topK, topP
genkit/ai/generate/output_images Flow_path, Modell, Temperatur, TopK, TopP
genkit/ai/generate/latency flow_path, model, temperature, topK, topP, error_code, error_message

Messwerte lassen sich im Metrics Explorer visualisieren. Wählen Sie im Seitenmenü „Logging“ (Protokollierung) und dann „Metrics Explorer“ (Messwert-Explorer) aus.

Wählen Sie einen Messwert aus, indem Sie auf das Drop-down-Menü „Messwert auswählen“ klicken und „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 zu einer leichten Verzögerung kommen, bis Telemetrie für eine bestimmte Ausführung eines Ablaufs in der Operations-Suite von Cloud angezeigt wird. In den meisten Fällen dauert es weniger als eine Minute.

Kontingente und Limits

Es gibt mehrere Kontingente, die Sie beachten sollten:

Kosten

Cloud Logging, Cloud Trace und Cloud Monitoring bieten großzügige kostenlose Stufen. Die spezifischen Preise finden Sie unter den folgenden Links: