編寫 Genkit 遙測外掛程式

Firebase Genkit 程式庫採用 OpenTelemetry 檢測 支援收集追蹤記錄、指標和記錄檔Genkit 使用者可以匯出這項資訊 安裝 設定 OpenTelemetry Go SDK 將資料匯出至支援 OpenTelemetry 的特定系統。

Genkit 包含一個外掛程式，可用來設定 OpenTelemetry，以便將資料匯出至 Google Cloud Monitoring 和 Cloud Logging：提供支援 可以編寫遙測外掛程式來擴充 Genkit 按照本頁所述的方式停用

事前準備

如需編寫程式的相關資訊，請參閱「編寫 Genkit 外掛程式」一文 任何類型的 Genkit 外掛程式，包括遙測外掛程式。請特別注意 每個外掛程式都必須匯出 Init 函式，且使用者應呼叫該函式。 完成後才能使用外掛程式

匯出工具和記錄器

如前所述，遙測外掛程式的主要工作是 OpenTelemetry (已校準 Genkit) 可用來匯出資料 附加至特定服務為此，您需要符合以下條件：

  • OpenTelemetry 的 SpanExporter 實作 介面，讓您將資料匯出至所選服務。
  • OpenTelemetry 的 metric.Exporter 實作 介面，讓您將資料匯出至所選服務。
  • slog.Logger 也可以實作 slog.Handler 介面，將記錄匯出至您選擇的服務。

視您想匯出的目標服務而定 只需要投入少量心力或龐大人心

由於 OpenTelemetry 是業界標準，因此許多監控服務已 或實作這些介面的程式庫。例如：googlecloud Genkit 外掛程式將 opentelemetry-operations-go 程式庫，由 Google Cloud 團隊維護 同樣地，許多監控服務提供的程式庫 標準 slog 介面。

另一方面，如果您的服務沒有這類程式庫， 實作必要介面可能會是重大的專案。

查看 OpenTelemetry 登錄檔 或監控服務的說明文件，確認是否已提供整合功能。

如果您需要自行建構這些整合項目，請查看 OpenTelemetry 官方匯出工具 以及《編寫 slog 處理常式指南》一文。

建構外掛程式

依附元件

每個遙測外掛程式都需要匯入 Genkit 核心程式庫和數個 OpenTelemetry 程式庫：

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"
}

如果您要以現有的 OpenTelemetry 或 slog 建構外掛程式 整合後，您也需要匯入這些素材資源。

Config

遙測外掛程式應至少支援下列設定 選項：

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
}

下方列舉的示例假設您已啟用這些選項 然後提供一些處理方式

大多數外掛程式也會提供該服務的配置設定 匯出至 (API 金鑰、專案名稱等)

Init()

遙測外掛程式的 Init() 函式應執行以下所有操作：

  • 如果 Genkit 是在開發環境中執行 (例如 與 genkit start 一併執行)，但Config.ForceExport 選項並未 設定：

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

  • 初始化追蹤記錄時距匯出工具，並透過 Genkit 註冊：

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

  • 初始化指標匯出工具，並向 OpenTelemetry 註冊指標 程式庫：

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

    下列情況應採用使用者設定的收集間隔 (Config.MetricInterval) 初始化 PeriodicReader。

  • 將 slog 處理常式註冊為預設記錄器：

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

    您應該設定處理常式以遵循使用者指定的最低記錄 等級 (Config.LogLevel)。

個人識別資訊遮蓋

大多數生成式 AI 流程都是從使用者輸入的內容開始 有些流程追蹤記錄可能包含個人識別資訊 資訊 (PII)。保護使用者應遮蓋 PII 擷取及擷取追蹤記錄

如果您正在建構自己的時距匯出工具，可以建構這項功能 加入。

如果您是使用現有的 OpenTelemetry 整合服務來建構外掛程式， 可以透過執行此動作的自訂匯出工具包裝所提供的時距匯出工具 工作。舉例來說，googlecloud 外掛程式會移除 genkit:input 和 使用包裝函式匯出每個跨距的 genkit:output 屬性 類似這樣：

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
}

疑難排解

如果無法根據預期顯示資料，OpenTelemetry 提供了實用的診斷工具 有助於找出問題來源