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:
- AlwaysOnSampler: Alle Traces werden als Stichprobe genommen.
- AlwaysOffSampler – keine Traces werden erfasst
- ParentBased – Stichproben basierend auf dem ü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.
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:
- Cloud Trace-Kontingente
- 128 Byte pro Attributschlüssel
- 256 Byte pro Attributwert
- Cloud Logging-Kontingente
- 256 KB pro Logeintrag
- Kontingente für Cloud Monitoring
Kosten
Cloud Logging, Cloud Trace und Cloud Monitoring bieten großzügige kostenlose Stufen. Die spezifischen Preise finden Sie unter den folgenden Links: