كتابة مكوّن إضافي للقياس عن بُعد من Genkit

يتم قياس مكتبات Firebase Genkit باستخدام OpenTelemetry، لدعم جمع بيانات التتبُّع والمقاييس والسجلات. يمكن لمستخدمي Genkit تصدير هذا من بيانات القياس عن بُعد لأدوات المراقبة والتصور عن طريق تثبيت مكون إضافي ضبط حزمة تطوير البرامج (SDK) OpenTelemetry Go التصدير إلى نظام معين يدعم OpenTelemetry.

تتضمن Genkit مكونًا إضافيًا يهيئ OpenTelemetry لتصدير البيانات إلى Google Cloud Monitoring وCloud Logging للدعم وأنظمة مراقبة أخرى، يمكنك توسيع Genkit عن طريق كتابة مكون إضافي للقياس عن بُعد، كما هو موضح في هذه الصفحة.

قبل البدء

يمكنك الاطّلاع على كتابة مكوّنات Genkit الإضافية للحصول على معلومات حول الكتابة. لأي نوع من مكوّنات Genkit الإضافية، بما في ذلك المكوّنات الإضافية للقياس عن بُعد. وعلى وجه الخصوص، لاحظ أن يجب أن يصدِّر كل مكوّن إضافي دالة Init، والتي من المتوقّع أن يستدعيها المستخدمون. قبل استخدام المكون الإضافي.

المصدِّرون ومدوّنات التسجيل

كما ذكرنا سابقًا، تتمثل المهمة الأساسية للمكون الإضافي للقياس عن بُعد في تهيئة أداة OpenTelemetry (التي تم الاستفادة منها حاليًا في Genkit) لتصدير البيانات لخدمة معيّنة. لإجراء ذلك، تحتاج إلى ما يلي:

• تنفيذ SpanExporter في OpenTelemetry تعمل على تصدير البيانات إلى الخدمة التي تختارها.
• تنفيذ metric.Exporter في OpenTelemetry تعمل على تصدير البيانات إلى الخدمة التي تختارها.
• إما 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
}

تفترض الأمثلة التالية أنك تتيح هذه الخيارات وست تقديم بعض الإرشادات حول كيفية التعامل معها.

ستتضمن معظم المكونات الإضافية أيضًا إعدادات الضبط للخدمة التي التصدير إلى (مفتاح واجهة برمجة التطبيقات واسم المشروع وما إلى ذلك)

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).

إخفاء معلومات تحديد الهوية الشخصية

ونظرًا لأن معظم تدفقات الذكاء الاصطناعي التوليدي تبدأ بإدخالات المستخدم، فإنه الاحتمال المحتمل أن تحتوي بعض عمليات تتبُّع التدفق على معلومات تحديد الهوية الشخصية معلومات (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. توفّر أداة تشخيص مفيدة التي تساعد في تحديد مصدر المشكلة.