Viết một trình bổ trợ đo từ xa Genkit

Thư viện Firebase Genkit được đo lường bằng OpenTelemetry để hỗ trợ việc thu thập dấu vết, chỉ số và nhật ký. Người dùng Genkit có thể xuất nội dung này dữ liệu đo từ xa đến các công cụ giám sát và trực quan hoá bằng cách cài đặt một trình bổ trợ định cấu hình SDK OpenTelemetry Go để xuất sang một hệ thống cụ thể có hỗ trợ OpenTelemetry.

Genkit bao gồm một trình bổ trợ định cấu hình OpenTelemetry để xuất dữ liệu sang Google Cloud Giám sát và Ghi nhật ký trên đám mây. Để hỗ trợ các hệ thống giám sát khác, bạn có thể mở rộng Genkit bằng cách viết một trình bổ trợ đo từ xa, như mô tả trên trang này.

Trước khi bắt đầu

Đọc trình bổ trợ Viết Genkit để biết thông tin về cách viết bất kỳ loại trình bổ trợ Genkit nào, bao gồm cả trình bổ trợ đo từ xa. Cụ thể, xin lưu ý rằng mỗi trình bổ trợ đều phải xuất một hàm Init. Đây là hàm mà người dùng dự kiến sẽ gọi trước khi sử dụng trình bổ trợ.

Nhà xuất khẩu và Người ghi nhật ký

Như đã đề cập trước đó, nhiệm vụ chính của trình bổ trợ đo từ xa là định cấu hình OpenTelemetry (công cụ mà Genkit đã được đo lường) để xuất dữ liệu vào một dịch vụ cụ thể. Để làm được điều này, bạn cần có:

  • Hoạt động triển khai SpanExporter của OpenTelemetry để xuất dữ liệu sang dịch vụ bạn chọn.
  • Hoạt động triển khai metric.Exporter của OpenTelemetry để xuất dữ liệu sang dịch vụ bạn chọn.
  • slog.Logger hoặc triển khai slog.Handler để xuất nhật ký sang dịch vụ mà bạn chọn.

Tuỳ thuộc vào dịch vụ mà bạn muốn xuất sang, đây có thể là công sức tương đối nhỏ hoặc lớn.

Vì OpenTelemetry là tiêu chuẩn ngành, nhiều dịch vụ giám sát đã có thư viện triển khai các giao diện này. Ví dụ: googlecloud trình bổ trợ cho Genkit tận dụng opentelemetry-operations-go do nhóm Google Cloud duy trì. Tương tự, nhiều dịch vụ giám sát cung cấp các thư viện triển khai giao diện slog chuẩn.

Mặt khác, nếu không có thư viện nào như vậy cho dịch vụ của bạn, việc triển khai các giao diện cần thiết có thể là một dự án lớn.

Kiểm tra đăng ký OpenTelemetry hoặc tài liệu của dịch vụ giám sát để xem liệu đã có chế độ tích hợp hay chưa.

Nếu bạn cần tự xây dựng các công cụ tích hợp này, hãy xem nguồn nhà xuất khẩu chính thức của OpenTelemetry và trang Hướng dẫn cách viết trình xử lý slog.

Xây dựng trình bổ trợ

Phụ thuộc

Mọi trình bổ trợ đo từ xa đều cần nhập thư viện lõi Genkit và một vài Các thư viện 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"
}

Nếu bạn đang tạo một trình bổ trợ dựa trên một OpenTelemetry hoặc slog hiện có tích hợp, bạn cũng sẽ cần nhập chúng.

Config

Trình bổ trợ đo từ xa tối thiểu phải hỗ trợ cấu hình sau tùy chọn:

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
}

Các ví dụ sau giả định rằng bạn đang cung cấp các lựa chọn này và sẽ hãy cung cấp một số hướng dẫn về cách xử lý.

Hầu hết các trình bổ trợ cũng sẽ bao gồm các chế độ cài đặt cấu hình cho dịch vụ của trình bổ trợ đó xuất sang (khoá API, tên dự án, v.v.).

Init()

Hàm Init() của một trình bổ trợ đo từ xa phải thực hiện tất cả những việc sau:

  • Trả lại sớm nếu Genkit đang chạy trong môi trường phát triển (chẳng hạn như khi chạy bằng genkit start) và tuỳ chọn Config.ForceExport thì không đặt:

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

  • Khởi chạy trình xuất span theo dõi rồi đăng ký trình xuất đó với Genkit:

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

  • Khởi chạy trình xuất chỉ số và đăng ký trình xuất chỉ số đó với OpenTelemetry thư viện:

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

    Sử dụng khoảng thời gian thu thập do người dùng thiết lập (Config.MetricInterval) khi khởi tạo PeriodicReader.

  • Đăng ký trình xử lý slog làm trình ghi nhật ký mặc định:

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

    Bạn nên định cấu hình trình xử lý để tuân thủ nhật ký tối thiểu do người dùng chỉ định cấp độ (Config.LogLevel).

Loại bỏ thông tin nhận dạng cá nhân (PII)

Vì hầu hết các quy trình AI tạo sinh đều bắt đầu bằng hoạt động đầu vào của người dùng, nên đây là khả năng một số dấu vết luồng chứa thông tin nhận dạng cá nhân thông tin nhận dạng cá nhân (PII). Để bảo vệ thông tin cá nhân, bạn nên loại bỏ PII khỏi các dấu vết trước khi xuất.

Nếu đang xây dựng trình xuất span của riêng mình, bạn có thể tạo chức năng này vào ứng dụng.

Nếu bạn xây dựng trình bổ trợ xung quanh một tích hợp OpenTelemetry hiện có, có thể kết hợp trình xuất span được cung cấp bằng một trình xuất dữ liệu tuỳ chỉnh thực hiện việc này công việc. Ví dụ: trình bổ trợ googlecloud sẽ xoá genkit:input và Thuộc tính genkit:output từ mọi span trước khi xuất các thuộc tính đó bằng một trình bao bọc tương tự như sau:

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
}

Khắc phục sự cố

Nếu bạn gặp sự cố để hiển thị dữ liệu ở nơi bạn mong đợi, OpenTelemetry cung cấp công cụ chẩn đoán hữu ích giúp xác định nguồn gốc vấn đề.