Genkit-Telemetrie-Plug-in schreiben

Die Firebase Genkit-Bibliotheken sind mit OpenTelemetry instrumentiert, um Traces, Messwerte und Protokolle zu erfassen. Genkit-Nutzer können diese Telemetriedaten in Monitoring- und Visualisierungstools exportieren, indem sie ein Plug-in installieren, das das OpenTelemetry Go SDK für den Export in ein bestimmtes OpenTelemetry-kompatibles System konfiguriert.

Genkit enthält ein Plug-in, das OpenTelemetry so konfiguriert, dass Daten in Google Cloud Monitoring und Cloud Logging: Zur Unterstützung Monitoringsystemen verwenden, können Sie Genkit mit einem Telemetrie-Plug-in erweitern, wie auf dieser Seite beschrieben.

Hinweis

Informationen zum Schreiben von Genkit-Plug-ins finden Sie unter Schreiben von Genkit-Plug-ins. Genkit-Plug-ins, einschließlich Telemetrie-Plug-ins. Beachten Sie insbesondere, dass jedes Plug-in eine Init-Funktion exportieren muss, die Nutzer vor der Verwendung des Plug-ins aufrufen müssen.

Exporteure und Holzfäller

Wie bereits erwähnt, besteht die Hauptaufgabe eines Telemetry-Plug-ins darin, OpenTelemetry (mit dem Genkit bereits instrumentiert wurde) so zu konfigurieren, dass Daten in einen bestimmten Dienst exportiert werden. Dazu benötigen Sie Folgendes:

Implementierung der SpanExporter von OpenTelemetry Schnittstelle, über die Daten an den Dienst Ihrer Wahl exportiert werden.
Implementierung der metric.Exporter von OpenTelemetry Schnittstelle, über die Daten an den Dienst Ihrer Wahl exportiert werden.
Entweder ein slog.Logger oder eine Implementierung der slog.Handler-Schnittstelle, die Protokolle in den Dienst Ihrer Wahl exportiert.

Je nach Dienst, in den Sie exportieren möchten, kann dies ein mit relativ geringem oder großem Aufwand.

Da OpenTelemetry ein Industriestandard ist, haben viele Monitoring-Dienste bereits Bibliotheken, die diese Schnittstellen implementieren. Beispiel: googlecloud für Genkit nutzt das opentelemetry-operations-go Bibliothek, die vom Google Cloud-Team gepflegt wird. Ebenso stellen viele Monitoringdienste Bibliotheken bereit, die den Standardmäßige slog-Schnittstellen.

Wenn für Ihren Dienst jedoch keine solchen Bibliotheken verfügbar sind, kann die Implementierung der erforderlichen Schnittstellen ein umfangreiches Projekt sein.

Sehen Sie in der OpenTelemetry-Registry oder in der Dokumentation des Monitoring-Dienstes nach, ob bereits Integrationen verfügbar sind.

Wenn Sie diese Integrationen selbst erstellen müssen, sehen Sie sich die Quelle der offiziellen OpenTelemetry-Exporter und die Seite A Guide to Writing slog Handlers an.

Plug-in erstellen

Abhängigkeiten

Jedes Telemetry-Plug-in muss die Genkit-Kernbibliothek und mehrere OpenTelemetry-Bibliotheken importieren:

import {
	// Import the Genkit core library.

	"github.com/firebase/genkit/go/genkit"

	// Import the OpenTelemetry libraries.
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/metric"
	"go.opentelemetry.io/otel/sdk/trace"
}

Wenn Sie ein Plug-in für eine vorhandene OpenTelemetry- oder slog-Integration erstellen, müssen Sie diese auch importieren.

`Config`

Ein Telemetry-Plug-in sollte mindestens die folgenden Konfigurationsoptionen unterstützen:

type Config struct {
	// Export even in the dev environment.
	ForceExport bool

	// The interval for exporting metric data.
	// The default is 60 seconds.
	MetricInterval time.Duration

	// The minimum level at which logs will be written.
	// Defaults to [slog.LevelInfo].
	LogLevel slog.Leveler
}

In den folgenden Beispielen wird davon ausgegangen, dass Sie diese Optionen zur Verfügung stellen. wie Sie damit umgehen können.

Die meisten Plug-ins enthalten auch Konfigurationseinstellungen für den Dienst, in den die Daten exportiert werden sollen (API-Schlüssel, Projektname usw.).

`Init()`

Die Init()-Funktion eines Telemetry-Plug-ins sollte Folgendes tun:

Kehren Sie frühzeitig zurück, wenn Genkit in einer Entwicklungsumgebung ausgeführt wird (z. B. wenn der mit genkit start ausgeführt wird, und die Option Config.ForceExport ist nicht festlegen:
```
shouldExport := cfg.ForceExport || os.Getenv("GENKIT_ENV") != "dev"
if !shouldExport {
	return nil
}
```

Initialisieren Sie den Trace-Span-Exporter und registrieren Sie ihn bei Genkit:

spanProcessor := trace.NewBatchSpanProcessor(YourCustomSpanExporter{})
genkit.RegisterSpanProcessor(g, spanProcessor)

Messwertexporter initialisieren und bei OpenTelemetry registrieren Bibliothek:
```
r := metric.NewPeriodicReader(
	YourCustomMetricExporter{},
	metric.WithInterval(cfg.MetricInterval),
)
mp := metric.NewMeterProvider(metric.WithReader(r))
otel.SetMeterProvider(mp)
```
Das vom Nutzer konfigurierte Erfassungsintervall (Config.MetricInterval) verwenden, wenn PeriodicReader wird initialisiert.
Registrieren Sie den slog-Handler als Standard-Protokollierung:
```
logger := slog.New(YourCustomHandler{
	Options: &slog.HandlerOptions{Level: cfg.LogLevel},
})
slog.SetDefault(logger)
```
Sie sollten Ihren Handler so konfigurieren, dass die vom Nutzer angegebene Mindestprotokollebene (Config.LogLevel) berücksichtigt wird.

Personenidentifizierbare Informationen entfernen

Da die meisten generativen KI-Abläufe mit einer Art von Nutzereingabe beginnen, ist es wahrscheinlich, dass einige Ablauf-Traces personenidentifizierbare Informationen enthalten. Zum Schutz der Daten Ihrer Nutzer sollten Sie PII aus den Traces entfernen, bevor Sie sie exportieren.

Wenn Sie Ihren eigenen Span-Exporter erstellen, können Sie diese Funktionalität erstellen. drauflosspielen.

Wenn Sie Ihr Plug-in auf einer vorhandenen OpenTelemetry-Integration aufbauen, können Sie den bereitgestellten SPAN-Exporteur in einen benutzerdefinierten Exporteur einbetten, der diese Aufgabe ausführt. Das Plug-in googlecloud entfernt beispielsweise genkit:input und genkit:output-Attribute aus jedem Span vor dem Exportieren mit einem Wrapper etwa so:

type redactingSpanExporter struct {
	trace.SpanExporter
}

func (e *redactingSpanExporter) ExportSpans(ctx context.Context, spanData []trace.ReadOnlySpan) error {
	var redacted []trace.ReadOnlySpan
	for _, s := range spanData {
		redacted = append(redacted, redactedSpan{s})
	}
	return e.SpanExporter.ExportSpans(ctx, redacted)
}

func (e *redactingSpanExporter) Shutdown(ctx context.Context) error {
	return e.SpanExporter.Shutdown(ctx)
}

type redactedSpan struct {
	trace.ReadOnlySpan
}

func (s redactedSpan) Attributes() []attribute.KeyValue {
	// Omit input and output, which may contain PII.
	var ts []attribute.KeyValue
	for _, a := range s.ReadOnlySpan.Attributes() {
		if a.Key == "genkit:input" || a.Key == "genkit:output" {
			continue
		}
		ts = append(ts, a)
	}
	return ts
}

Fehlerbehebung

Wenn Sie Probleme haben, Daten an der gewünschten Stelle anzuzeigen, kann OpenTelemetry bietet ein nützliches Diagnose-Tool um die Ursache des Problems zu finden.