כתיבת פלאגין של טלמטריה ב-Genkit

ספריות Firebase Genkit כוללות OpenTelemetry כדי לתמוך באיסוף של נתוני מעקב, מדדים ויומנים. משתמשי Genkit יכולים לייצא את נתוני הטלמטריה האלה לכלים למעקב ולתצוגה חזותית על ידי התקנת פלאגין שמגדיר את OpenTelemetry Go SDK לייצוא למערכת מסוימת שתומכת ב-OpenTelemetry.

Genkit כולל פלאגין שמגדיר את OpenTelemetry לייצא נתונים אל Google Cloud Monitoring ו-Cloud Logging. כדי לתמוך במערכות מעקב אחרות, אפשר להרחיב את Genkit על ידי כתיבת פלאגין טלמטריה, כפי שמתואר בדף הזה.

לפני שמתחילים

למידע על כתיבה, אפשר לקרוא את המאמר כתיבת יישומי פלאגין של Genkit כל סוג של פלאגין של Genkit, כולל יישומי פלאגין של טלמטריה. באופן ספציפי, שימו לב כל פלאגין חייב לייצא פונקציית Init, שאליה המשתמשים צפויים לקרוא לפני השימוש בפלאגין.

פונקציות ייצוא ופונקציות רישום ביומן

כפי שצוין קודם, המשימה העיקרית של פלאגין טלמטריה היא להגדיר OpenTelemetry (שכבר נעשה בו שימוש ב-Genkit) כדי לייצא נתונים לשירות מסוים. כדי לעשות זאת, צריך את הפרטים הבאים:

• הטמעה של ממשק SpanExporter של OpenTelemetry, שמייצא נתונים לשירות שבחרתם.
• הטמעה של OpenTelemetry metric.Exporter ממשק שמייצא נתונים לשירות הרצוי.
• slog.Logger או הטמעה של הממשק slog.Handler, שמייצא יומנים לשירות הרצוי.

בהתאם לשירות שאליו רוצים לייצא, זו עשויה להיות מאמץ קטן יחסית או גדול.

כיוון ש-OpenTelemetry הוא תקן מקובל בתחום, שירותי מעקב רבים כבר יש ספריות שמטמיעות את הממשקים האלה. לדוגמה, googlecloud ל-Genkit משתמש opentelemetry-operations-go שמנוהל על ידי צוות Google Cloud. באופן דומה, שירותי מעקב רבים מספקים ספריות שמטמיעות את ממשקי slog הרגילים.

מצד שני, אם אין ספריות כאלה זמינות לשירות שלכם, הטמעת הממשקים הנדרשים יכולה להיות פרויקט משמעותי.

צריך לבדוק ברישום OpenTelemetry או במסמכים של שירות המעקב כדי לבדוק אם כבר יש שילובים זמינים.

אם אתם צריכים ליצור את השילובים האלה בעצמכם, כדאי לעיין בקוד המקור של ייצוא הנתונים הרשמי של OpenTelemetry ובדף מדריך לכתיבת Handlers של slog.

פיתוח הפלאגין

יחסי תלות

כל פלאגין של טלמטריה צריך לייבא את ספריית הליבה של Genkit ספריות 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"
}

אם אתם מפתחים פלאגין שמבוסס על שילוב קיים של 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 לא set:

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

• מפעילים את הייצוא של קטעי המעקב ומרשמים אותו ב-Genkit:

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

• מפעילים את הייצוא של המדדים ומרשמים אותו בספרייה של OpenTelemetry:

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

  שימוש במרווח הזמן שהוגדר על ידי המשתמש לאיסוף (Config.MetricInterval) כאשר באתחול של PeriodicReader.

• רושמים את ה-handler של slog כיומן ברירת המחדל:

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

  צריך להגדיר את ה-handler כך שיציית לרמת היומן המינימלית שצוינה על ידי המשתמש (Config.LogLevel).

השמטת פרטים אישיים מזהים (PII)

מאחר שרוב תהליכי ה-AI הגנרטיביים מתחילים בהזנה של משתמש מסוג כלשהו, סביר להניח שחלק מהמעקבים אחר התהליכים מכילים פרטים אישיים מזהים (PII). כדי להגן על המשתמשים צריך לצנזר פרטים אישיים מזהים (PII) מעקבות לפני שתייצאו אותם.

אם אתם מפתחים ייצוא span משלכם, תוכלו להטמיע את הפונקציונליות הזו בו.

אם בונים את הפלאגין סביב שילוב קיים של OpenTelemetry, יכול לארוז את יצואן טווחים שסופק עם יצואן מותאם אישית שמבצע למשימה הזו. לדוגמה, הפלאגין googlecloud מסיר את הקוד genkit:input וגם genkit:output מאפיינים מכל טווח לפני שמייצאים אותם באמצעות wrapper כמו:

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 מספק כלי אבחון שימושי שעוזר לאתר את מקור הבעיה.