Genkit telemetri eklentisi yazma

Firebase Genkit kitaplıkları, OpenTelemetry ile uyumludur performansa dayanıyor. Genkit kullanıcıları bunu dışa aktarabilir telemetri verilerini izleme ve görselleştirme araçlarına aktaran bir eklenti yükleyerek OpenTelemetry Go SDK'yı yapılandırır OpenTemetri özellikli belirli bir sisteme aktarmak için aşağıdaki adımları uygulayın.

Genkit, verileri dışa aktarmak için OpenTelemetry'yi yapılandıran bir eklenti içerir. Google Cloud Monitoring ve Cloud Logging. Destek ekibi bir telemetri eklentisi yazarak Genkit'i genişletebilirsiniz. bu sayfada açıklandığı gibidir.

Başlamadan önce

Yazma hakkında bilgi edinmek için Genkit eklentileri yazma başlıklı makaleyi okuyun telemetri eklentileri dahil her türlü Genkit eklentisi. Özellikle, her bir her eklenti, kullanıcıların çağırması gereken bir Init işlevini dışa aktarmalıdır. kontrol edin.

Dışa Aktarıcılar ve Günlük Kaydediciler

Daha önce belirtildiği gibi, telemetri eklentisinin birincil işi Verileri dışa aktarmak için OpenTelemetry (Genkit'in halihazırda optimize edildiği) geliştirmenizi sağlar. Bunun için gerekenler:

• OpenTelemetry SpanExporter uygulaması dışa aktaran bir arayüz oluşturabilirsiniz.
• OpenTelemetry metric.Exporter uygulaması dışa aktaran bir arayüz oluşturabilirsiniz.
• slog.Logger veya slog.Handler uygulanması günlüklerin seçtiğiniz hizmete aktarılmasına olanak tanır.

Dışa aktarmak istediğiniz hizmete bağlı olarak, veya büyük bir çaba gerektirebilir.

OpenTelemetry bir endüstri standardı olduğundan, birçok izleme hizmeti zaten bu arayüzleri uygulayan kitaplıklar vardır. Örneğin, googlecloud Genkit eklentisi, opentelemetry-operations-go kitaplığını kullanırsınız. Benzer şekilde, birçok izleme hizmeti standart slog arayüzleridir.

Diğer yandan, hizmetiniz için böyle bir kitaplık yoksa, uygulamak büyük bir proje olabilir.

OpenTelemetry kayıt defterini kontrol edin veya izleme hizmetinin dokümanlarına bakabilirsiniz.

Bu entegrasyonları kendiniz oluşturmanız gerekiyorsa bu entegrasyonun kaynağını inceleyin resmi OpenTelememetri ihracatçıları ve slog İşleyicileri Yazma Kılavuzu'na bakabilirsiniz.

Eklentiyi oluşturma

Bağımlılıklar

Her telemetri eklentisinin, Genkit çekirdek kitaplığını ve OpenTelemetry kitaplıkları:

import {
	// Import the Genkit core library.
	"github.com/firebase/genkit/go/core"

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

Mevcut bir OpenTelemetry veya slog etrafında eklenti oluşturuyorsanız bunları içe aktarmanız da gerekir.

Config

Bir telemetri eklentisi en azından aşağıdaki yapılandırmayı desteklemelidir seçenekler:

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
}

Aşağıdaki örneklerde bu seçenekleri kullanıma sunduğunuz ve sizin nasıl ele alınacağına ilişkin yol gösterici bilgiler verilmektedir.

Çoğu eklenti, çalıştığı hizmetin yapılandırma ayarlarını da dışa aktarma (API anahtarı, proje adı vs.).

Init()

Telemetri eklentisinin Init() işlevi aşağıdakilerin tümünü yapmalıdır:

• Genkit bir geliştirme ortamında çalışıyorsa (örneğin, genkit start ile çalışıyor) ve Config.ForceExport seçeneği grup:

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

• İz aralığı dışa aktarıcınızı başlatın ve Genkit'e kaydedin:

  spanProcessor := trace.NewBatchSpanProcessor(YourCustomSpanExporter{})
  core.RegisterSpanProcessor(spanProcessor)
  

• Metrik dışa aktarıcınızı başlatın ve OpenTelemetry ile kaydedin kitaplık:

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

  Aşağıdaki durumlarda kullanıcı tarafından yapılandırılan toplama aralığını (Config.MetricInterval) kullan PeriodicReader başlatılıyor.

• slog işleyicinizi varsayılan günlükçü olarak kaydedin:

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

  İşleyicinizi kullanıcı tarafından belirtilen minimum günlüğü dikkate alacak şekilde yapılandırmanız gerekir. Config.LogLevel seviyesindedir.

Kimliği tanımlayabilecek bilgileri (PII) azaltma

Çoğu üretken yapay zeka akışı bir tür kullanıcı girişiyle başladığından, bazı akış izlerinin kimliği tanımlayabilecek bilgiler içerme olasılığı kimliği tanımlayabilecek bilgiler (PII) Kullanıcılarınızın güvenliğini kimliği tanımlayabilecek bilgileri (PII) kaldırın.

Kendi span ihracatçınızı oluşturuyorsanız bu işlevi inceleyeceğiz.

Eklentinizi mevcut bir OpenTelemetry entegrasyonu etrafında oluşturuyorsanız sağlanan span dışa aktarıcısını, bu işlemi gerçekleştiren özel bir ihracatçı ile sarmalayabilir. görevi görebilir. Örneğin, googlecloud eklentisi, genkit:input ve Sarmalayıcı kullanarak dışa aktarmadan önce her aralıktan genkit:output özelliği aşağıdakine benzer:

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
}

Sorun giderme

Verilerin beklediğiniz yerde görünmesini sağlama konusunda sorun yaşıyorsanız OpenTelemetry yararlı bir teşhis aracı sunar bir çözüm bulmanız gerekir.