Le librerie Firebase Genkit sono strumentate con OpenTelemetry per supportare la raccolta di tracce, metriche e log. Gli utenti Genkit possono esportare questo di dati di telemetria agli strumenti di monitoraggio e visualizzazione mediante l'installazione di un plug-in configura l'SDK OpenTelemetry Go da esportare in un particolare sistema compatibile con OpenTelemetry.
Genkit include un plug-in che configura OpenTelemetry per esportare i dati in Google Cloud Monitoring e Cloud Logging. Per supportare altri sistemi di monitoraggio, puoi estendere Genkit scrivendo un plug-in di telemetria, come descritto in questa pagina.
Prima di iniziare
Per informazioni sulla scrittura di plug-in Genkit, consulta Scrittura di plug-in Genkit
qualsiasi tipo di plug-in Genkit, compresi quelli di telemetria. In particolare, tieni presente che ogni plug-in deve esportare una funzione Init
che gli utenti devono chiamare prima di utilizzare il plug-in.
Esportatori e logger
Come già detto in precedenza, il compito principale di un plug-in di telemetria è configurare OpenTelemetry (per il quale Genkit è già stato utilizzato) per esportare i dati a un particolare servizio. A questo scopo, ti serve quanto segue:
- Un'implementazione di
SpanExporter
di OpenTelemetry che esporta i dati nel servizio che preferisci. - Un'implementazione di
metric.Exporter
di OpenTelemetry che esporta i dati nel servizio che preferisci. - Un
slog.Logger
o un'implementazione dell'interfacciaslog.Handler
che esporta i log nel servizio che preferisci.
A seconda del servizio in cui vuoi eseguire l'esportazione, potrebbe essere una un impegno relativamente piccolo o grande.
Poiché OpenTelemetry è uno standard di settore, molti servizi di monitoraggio
dispongono di librerie che implementano
queste interfacce. Ad esempio, il plug-in googlecloud
per Genkit utilizza la libreria
opentelemetry-operations-go
gestita dal team di Google Cloud.
Analogamente, molti servizi di monitoraggio forniscono librerie che implementano
standard slog
.
D'altra parte, se non sono disponibili librerie di questo tipo per il tuo servizio, l'implementazione delle interfacce necessarie può essere un progetto importante.
Controlla il registro OpenTelemetry o la documentazione del servizio di monitoraggio per verificare se le integrazioni sono già disponibili.
Se devi creare personalmente queste integrazioni, dai un'occhiata alla fonte
Gli esportatori ufficiali di OpenTelemetry
e la pagina A Guide to Write slog
Gestori.
Creazione del plug-in
Dipendenze
Ogni plug-in di telemetria deve importare la libreria di base di Genkit e diverse librerie OpenTelemetry:
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"
}
Se stai creando un plug-in per un'integrazione OpenTelemetry o slog
esistente, dovrai anche importarli.
Config
Un plug-in di telemetria deve supportare, come minimo, le seguenti opzioni di configurazione:
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
}
Gli esempi riportati di seguito presuppongono che tu renda disponibili queste opzioni e forniranno alcune indicazioni su come gestirle.
La maggior parte dei plug-in include anche le impostazioni di configurazione per il servizio l'esportazione in (chiave API, nome progetto e così via).
Init()
La funzione Init()
di un plug-in di telemetria deve eseguire tutte le seguenti operazioni:
Torna in anticipo se Genkit è in esecuzione in un ambiente di sviluppo (ad esempio quando viene eseguito con
genkit start
) e l'opzioneConfig.ForceExport
non è impostata:shouldExport := cfg.ForceExport || os.Getenv("GENKIT_ENV") != "dev" if !shouldExport { return nil }
Inizializza l'esportatore di intervalli di traccia e registralo con Genkit:
spanProcessor := trace.NewBatchSpanProcessor(YourCustomSpanExporter{}) genkit.RegisterSpanProcessor(g, spanProcessor)
Inizializza l'esportatore di metriche e registralo con la biblioteca OpenTelemetry:
r := metric.NewPeriodicReader( YourCustomMetricExporter{}, metric.WithInterval(cfg.MetricInterval), ) mp := metric.NewMeterProvider(metric.WithReader(r)) otel.SetMeterProvider(mp)
Utilizza l'intervallo di raccolta configurato dall'utente (
Config.MetricInterval
) quando inizializzazione ilPeriodicReader
.Registra il gestore
slog
come logger predefinito:logger := slog.New(YourCustomHandler{ Options: &slog.HandlerOptions{Level: cfg.LogLevel}, }) slog.SetDefault(logger)
Devi configurare il gestore in modo da rispettare il log minimo specificato dall'utente livello (
Config.LogLevel
).
Oscuramento delle PII
Poiché la maggior parte dei flussi di IA generativa inizia con qualche tipo di input dell'utente, probabile che alcune tracce di flusso contengano l'identificazione personale di informazioni (PII). Per proteggere i tuoi utenti di informazioni, dovresti oscurare le informazioni che consentono l'identificazione personale (PII). dalle tracce prima di esportarle.
Se stai creando il tuo esportatore di span, puoi incorporare questa funzionalità.
Se stai creando il tuo plug-in sulla base di un'integrazione OpenTelemetry esistente,
può aggregare l'esportatore di intervalli fornito con un esportatore personalizzato che esegue
dell'attività. Ad esempio, il plug-in googlecloud
rimuove genkit:input
e
genkit:output
attributi da ogni intervallo prima di esportarli utilizzando un wrapper
simile al seguente:
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
}
Risoluzione dei problemi
Se hai difficoltà a visualizzare i dati dove previsto, OpenTelemetry offre un utile strumento di diagnostica che aiuta a individuare l'origine del problema.