Zapisywanie wtyczki telemetrycznej Genkit

Biblioteki Genkit są wyposażone w OpenTelemetry, aby umożliwić zbieranie śladów, wskaźników i logów. Użytkownicy Genkit mogą eksportować te dane telemetryczne do narzędzi do monitorowania i wizualizacji, instalując wtyczkę, która skonfiguruje pakiet OpenTelemetry Go SDK do eksportowania do konkretnego systemu obsługującego OpenTelemetry.

Genkit zawiera wtyczkę, która konfiguruje OpenTelemetry do eksportowania danych do Google Cloud Monitoring i Cloud Logging. Aby obsługiwać inne systemy monitorowania, możesz rozszerzyć Genkit o swój własny wtyczkę telemetryczną, korzystając z instrukcji podanych na tej stronie.

Zanim zaczniesz

Więcej informacji o tworzeniu dowolnego typu wtyczki Genkit, w tym wtyczek telemetrycznych, znajdziesz w artykule Tworzenie wtyczek Genkit. Zwróć uwagę, że każda wtyczka musi eksportować funkcję Init, którą użytkownicy muszą wywołać przed użyciem wtyczki.

Eksporterzy i rejestratorzy

Jak już wspomnieliśmy, główne zadanie wtyczki telemetrii polega na skonfigurowaniu OpenTelemetry (z którego Genkit jest już wyposażony) w celu eksportowania danych do konkretnej usługi. Aby to zrobić, musisz mieć:

  • Implementacja interfejsu SpanExporter OpenTelemetry, który eksportuje dane do wybranej usługi.
  • Implementacja interfejsu metric.Exporter OpenTelemetry, który eksportuje dane do wybranej usługi.
  • slog.Logger lub implementacja interfejsu slog.Handler, który eksportuje dzienniki do wybranej usługi.

W zależności od usługi, do której chcesz eksportować dane, może to wymagać stosunkowo niewielkiego lub dużego nakładu pracy.

OpenTelemetry jest standardem branżowym, dlatego wiele usług monitorowania ma już biblioteki, które implementują te interfejsy. Na przykład wtyczka googlecloud dla Genkit korzysta z biblioteki opentelemetry-operations-go, którą zarządza zespół Google Cloud. Podobnie wiele usług monitorowania udostępnia biblioteki, które implementują standardowe interfejsy slog.

Z drugiej strony, jeśli w przypadku Twojej usługi nie ma dostępnych takich bibliotek, wdrożenie niezbędnych interfejsów może być dużym projektem.

Aby sprawdzić, czy integracje są już dostępne, sprawdź rejestr OpenTelemetry lub dokumenty usługi monitorowania.

Jeśli chcesz samodzielnie tworzyć te integracje, zapoznaj się ze źródłem oficjalnych eksporterów OpenTelemetry oraz z artykułem Przewodnik po tworzeniu modułów obsługi slog.

Tworzenie wtyczki

Zależności

Każdy wtyczka telemetryczna musi importować bibliotekę główną Genkit i kilka bibliotek 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"
}

Jeśli tworzysz wtyczkę na podstawie istniejącej integracji OpenTelemetry lub slog, musisz ją też zaimportować.

Config

Wtyczka telemetryczna powinna obsługiwać co najmniej te opcje konfiguracji:

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
}

W przypadku poniższych przykładów zakładamy, że udostępniasz te opcje, i zawierają one wskazówki dotyczące ich obsługi.

Większość wtyczek zawiera też ustawienia konfiguracji usługi, do której dane są eksportowane (klucz API, nazwa projektu itp.).

Init()

Funkcja Init() w pliku telementryjnym powinna spełniać te wymagania:

  • Wróć wcześniej, jeśli Genkit działa w środowisku programistycznym (np. gdy działa z genkit start) i opcja Config.ForceExport nie jest ustawiona:

    shouldExport := cfg.ForceExport || os.Getenv("GENKIT_ENV") != "dev"
if !shouldExport {
	return nil
}

  • Inicjuj eksporter zakresu śladu i zarejestruj go w Genkit:

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

  • Inicjuj eksportera danych i zarejestruj go w bibliotece OpenTelemetry:

    r := metric.NewPeriodicReader(
	YourCustomMetricExporter{},
	metric.WithInterval(cfg.MetricInterval),
)
mp := metric.NewMeterProvider(metric.WithReader(r))
otel.SetMeterProvider(mp)

    Podczas inicjowania interfejsu PeriodicReader użyj skonfigurowanego przez użytkownika przedziału czasowego zbierania danych (Config.MetricInterval).

  • Zarejestruj moduł obsługi slog jako domyślny rejestrator:

    logger := slog.New(YourCustomHandler{
	Options: &slog.HandlerOptions{Level: cfg.LogLevel},
})
slog.SetDefault(logger)

    Musisz skonfigurować moduł obsługi, aby uwzględniał minimalny poziom logowania określony przez użytkownika (Config.LogLevel).

Usuwanie informacji umożliwiających identyfikację

Większość procesów generatywnej AI rozpoczyna się od danych wejściowych użytkownika, dlatego istnieje prawdopodobieństwo, że niektóre ścieżki mogą zawierać informacje umożliwiające identyfikację osoby. Aby chronić informacje o użytkownikach, przed wyeksportowaniem śladów usuń z nich dane osobowe.

Jeśli tworzysz własny eksporter zakresów, możesz dodać do niego tę funkcję.

Jeśli tworzysz wtyczkę na podstawie istniejącej integracji OpenTelemetry, możesz owinąć udostępniony eksporter sekcji za pomocą niestandardowego eksportera, który wykonuje tę czynność. Na przykład wtyczka googlecloud usuwa atrybuty genkit:input i genkit:output z każdego elementu, zanim wyeksportuje je za pomocą owijacza podobnego do tego:

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
}

Rozwiązywanie problemów

Jeśli masz problem z wyświetlaniem danych w oczekiwanym miejscu, OpenTelemetry udostępnia przydatne narzędzie diagnostyczne, które pomoże Ci zlokalizować źródło problemu.