نوشتن پلاگین تله متری Genkit

کتابخانه‌های Firebase Genkit با OpenTelemetry برای پشتیبانی از جمع‌آوری ردیابی‌ها، معیارها و گزارش‌ها مجهز شده‌اند. کاربران Genkit می‌توانند با نصب افزونه‌ای که OpenTelemetry Go SDK را برای صادرات به یک سیستم خاص با قابلیت OpenTelemetry پیکربندی می‌کند، این داده‌های تله‌متری را به ابزارهای نظارت و تجسم صادر کنند.

Genkit شامل افزونه‌ای است که OpenTelemetry را برای صادر کردن داده‌ها به Google Cloud Monitoring و Cloud Logging پیکربندی می‌کند. برای پشتیبانی از سایر سیستم های نظارتی، می توانید Genkit را با نوشتن یک پلاگین تله متری، همانطور که در این صفحه توضیح داده شده است، گسترش دهید.

قبل از شروع

برای اطلاعات در مورد نوشتن هر نوع پلاگین Genkit، از جمله پلاگین های تله متری ، افزونه های Writing Genkit را بخوانید. به طور خاص، توجه داشته باشید که هر افزونه باید یک تابع Init را صادر کند، که انتظار می رود کاربران قبل از استفاده از افزونه آن را فراخوانی کنند.

صادرکنندگان و چوبگیران

همانطور که قبلاً گفته شد، وظیفه اصلی یک پلاگین تله متری پیکربندی OpenTelemetry (که Genkit قبلاً با آن مجهز شده است) است تا داده ها را به یک سرویس خاص صادر کند. برای انجام این کار، به موارد زیر نیاز دارید:

• اجرای رابط SpanExporter OpenTelemetry که داده ها را به سرویس مورد نظر شما صادر می کند.
• پیاده سازی رابط metric.Exporter OpenTelemetry که داده ها را به سرویس مورد نظر شما صادر می کند.
• یا یک slog.Logger یا یک پیاده‌سازی از رابط slog.Handler که گزارش‌ها را به سرویس انتخابی شما صادر می‌کند.

بسته به خدماتی که می‌خواهید به آن صادر کنید، این ممکن است یک تلاش نسبتاً جزئی یا بزرگ باشد.

از آنجایی که OpenTelemetry یک استاندارد صنعتی است، بسیاری از خدمات نظارتی در حال حاضر دارای کتابخانه هایی هستند که این رابط ها را پیاده سازی می کنند. به عنوان مثال، افزونه googlecloud برای Genkit از کتابخانه opentelemetry-operations-go که توسط تیم Google Cloud نگهداری می شود، استفاده می کند. به طور مشابه، بسیاری از خدمات نظارتی کتابخانه‌هایی را ارائه می‌کنند که رابط‌های slog استاندارد را پیاده‌سازی می‌کنند.

از سوی دیگر، اگر چنین کتابخانه‌هایی برای خدمت شما در دسترس نباشد، پیاده‌سازی رابط‌های لازم می‌تواند پروژه‌ای اساسی باشد.

رجیستری OpenTelemetry یا اسناد سرویس مانیتورینگ را بررسی کنید تا ببینید آیا ادغام ها از قبل در دسترس هستند یا خیر.

اگر می‌خواهید خودتان این ادغام‌ها را بسازید، نگاهی به منبع صادرکنندگان رسمی OpenTelemetry و صفحه A Guide to Writing slog Handlers بیندازید.

ساخت افزونه

وابستگی ها

هر پلاگین تله متری باید کتابخانه هسته 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)
  

  هنگام تنظیم اولیه PeriodicReader از فاصله مجموعه پیکربندی شده توسط کاربر ( Config.MetricInterval ) استفاده کنید.

• کنترل کننده slog خود را به عنوان گزارشگر پیش فرض ثبت کنید:

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

  باید کنترل کننده خود را طوری پیکربندی کنید که حداقل سطح گزارش مشخص شده توسط کاربر ( Config.LogLevel ) را رعایت کند.

ویرایش PII

از آنجایی که بیشتر جریان‌های هوش مصنوعی مولد با نوعی ورودی کاربر شروع می‌شوند، این احتمال وجود دارد که برخی از ردیابی‌های جریان حاوی اطلاعات شخصی قابل شناسایی (PII) باشند. برای محافظت از اطلاعات کاربران خود، باید PII را از ردیابی حذف کنید قبل از اینکه آنها را صادر کنید.

اگر صادرکننده دهانه خود را می سازید، می توانید این قابلیت را در آن ایجاد کنید.

اگر پلاگین خود را حول یک ادغام OpenTelemetry موجود می‌سازید، می‌توانید صادرکننده span ارائه شده را با یک صادرکننده سفارشی که این کار را انجام می‌دهد بپیچید. به عنوان مثال، افزونه 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 ابزار تشخیصی مفیدی را ارائه می دهد که به یافتن منبع مشکل کمک می کند.