يُصدِّر مكوّن Google Cloud الإضافي بيانات التتبُّع والتسجيل في Firebase Genkit إلى مجموعة عمليات Google Cloud التي تشغِّل لوحة بيانات مراقبة الذكاء الاصطناعي في Firebase (إصدار تجريبي خاص).
تثبيت
npm i --save @genkit-ai/google-cloudإذا كنت تريد تشغيل عمليات سير العمل التي تستخدِم هذا المكوّن الإضافي على الجهاز، يجب أيضًا تثبيت أداة Google Cloud CLI.
إعداد حساب على Google Cloud
يتطلب هذا المكوّن الإضافي حسابًا على Google Cloud (اشترِك إذا لم يكن لديك حساب) ومشروعًا على Google Cloud.
قبل إضافة المكوّن الإضافي، تأكَّد من تفعيل واجهات برمجة التطبيقات التالية لمشروعك:
يجب أن تكون واجهات برمجة التطبيقات هذه مُدرَجة في لوحة بيانات واجهة برمجة التطبيقات لمشروعك.
انقر هنا للاطّلاع على مزيد من المعلومات عن تفعيل واجهات برمجة التطبيقات وإيقافها.
إعدادات Genkit
لتفعيل التصدير إلى ميزة "التتبّع والتسجيل والمراقبة" في Google Cloud، ما عليك سوى الاتصال بالرقم enableGoogleCloudTelemetry():
import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';
enableGoogleCloudTelemetry();
عند التشغيل في مرحلة الإنتاج، يتم تصدير بيانات القياس تلقائيًا.
المصادقة
يتطلّب المكوّن الإضافي معرّف مشروع Google Cloud وبيانات اعتماد مشروعك على Google Cloud. إذا كنت تشغّل عملية المعالجة من بيئة Google Cloud (Cloud Functions وCloud Run وما إلى ذلك)، يتم ضبط معرّف المشروع وبيانات الاعتماد تلقائيًا.
بيانات الاعتماد التلقائية للتطبيق
يتطلّب التشغيل في بيئات أخرى ضبط متغيّر البيئة GCLOUD_PROJECT على مشروعك على Google Cloud والمصادقة باستخدام أداة gcloud:
gcloud auth application-default loginلمزيد من المعلومات، يُرجى الاطّلاع على مستندات بيانات الاعتماد التلقائية للتطبيق.
بيانات اعتماد حساب الخدمة
إذا كنت تستخدم حساب خدمة وكنت تعمل خارج بيئة Google Cloud، يمكنك ضبط بيانات الاعتماد كمتغيّر بيئة. اتّبِع التعليمات الواردة هنا لإعداد مفتاح حساب الخدمة في Google Cloud.
بعد تنزيل ملف المفاتيح، يمكنك تحديد بيانات الاعتماد بطريقتَين: موقع ملف باستخدام متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS أو نسخ محتوى ملف json مباشرةً إلى متغيّر البيئة GCLOUD_SERVICE_ACCOUNT_CREDS.
مسار الملف:
GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"
النص المباشر:
GCLOUD_SERVICE_ACCOUNT_CREDS='{
"type": "service_account",
"project_id": "your-project-id",
"private_key_id": "your-private-key-id",
"private_key": "your-private-key",
"client_email": "your-client-email",
"client_id": "your-client-id",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://accounts.google.com/o/oauth2/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "your-cert-url"
}'
إعداد المكوّن الإضافي
تأخذ الدالة enableGoogleCloudTelemetry() عنصر إعدادات اختياريًا يضبط مثيل OpenTelemetry NodeSDK.
import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';
enableGoogleCloudTelemetry({
forceDevExport: false, // Set this to true to export telemetry for local runs
sampler: new AlwaysOnSampler(),
autoInstrumentation: true,
autoInstrumentationConfig: {
'@opentelemetry/instrumentation-fs': { enabled: false },
'@opentelemetry/instrumentation-dns': { enabled: false },
'@opentelemetry/instrumentation-net': { enabled: false },
},
metricExportIntervalMillis: 5_000,
});
تسمح عناصر الضبط بالتحكّم بشكل دقيق في الجوانب المختلفة لتصدير بيانات القياس عن بُعد الموضّحة أدناه.
بيانات الاعتماد
يسمح بتحديد بيانات الاعتماد مباشرةً باستخدام JWTInput من مكتبة google-auth.
أداة أخذ العينات
في الحالات التي لا يكون فيها تصدير جميع عمليات التتبّع عمليًا، تسمح OpenTelemetry بتحليل عيّنات عمليات التتبّع.
هناك أربعة أدوات تحليل مُعدّة مسبقًا:
- AlwaysOnSampler: لتحليل عيّنات من جميع عمليات التتبّع
- AlwaysOffSampler: لا يتم جمع أيّ عيّنات
- ParentBased: عيّنات تستند إلى نطاق العنصر الرئيسي
- TraceIdRatioBased: تُستخدَم لتحليل نسبة مئوية قابلة للضبط من عمليات التتبّع
autoInstrumentation وautoInstrumentationConfig
يتيح تفعيل الأدوات التلقائية لـ OpenTelemetry تسجيل بيانات القياس عن بُعد من المكتبات التابعة لجهات خارجية بدون الحاجة إلى تعديل الرمز البرمجي.
metricExportIntervalMillis
يحدّد هذا الحقل الفاصل الزمني لتصدير المقاييس بالمللي ثانية.
metricExportTimeoutMillis
يحدّد هذا الحقل مهلة تصدير المقاييس بالمللي ثانية.
disableMetrics
يوفّر هذا الخيار إمكانية إلغاء تصدير المقاييس مع مواصلة تصدير عمليات التتبُّع والسجلّات.
disableTraces
يوفّر هذا الخيار إمكانية إيقاف تصدير عمليات التتبّع مع مواصلة تصدير المقاييس والسجلّات.
disableLoggingIO
يوفّر خيارًا لإيقاف جمع سجلات الإدخال والإخراج.
forceDevExport
سيؤدي هذا الخيار إلى إجبار Genkit على تصدير بيانات القياس عن بُعد والسجلّات عند تشغيله في بيئة dev (مثلاً على الجهاز).
اختبار عملية الدمج
عند ضبط المكوّن الإضافي، استخدِم forceDevExport: true لتفعيل تصدير بيانات التتبُّع لعمليات التشغيل المحلية. انتقِل إلى "سجلّات Google Cloud" أو "مقاييس Google Cloud" أو "مستكشف التتبّع" للاطّلاع على بيانات القياس. بدلاً من ذلك، انتقِل إلى لوحة بيانات "مراقبة الذكاء الاصطناعي" في Firebase (إصدار تجريبي خاص) للحصول على عرض مألوف للبيانات الوصفية باستخدام الذكاء الاصطناعي.