افزونه Google Cloud

افزونه Google Cloud تله متری Firebase Genkit و داده های گزارش را به مجموعه Cloud Observability صادر می کند.

نصب و راه اندازی 

npm i --save @genkit-ai/google-cloud

هنگام اجرای کد Genkit به صورت محلی که شامل این افزونه است، به ابزار Google Cloud CLI نیز نیاز دارید.

یک حساب Google Cloud راه اندازی کنید

این افزونه به حساب/پروژه Google Cloud نیاز دارد. همه پروژه‌های Firebase به‌طور پیش‌فرض شامل یکی ( کنسول GCP ) هستند، یا می‌توانید در https://cloud.google.com ثبت‌نام کنید.

قبل از افزودن افزونه، مطمئن شوید که APIهای زیر برای پروژه GCP شما فعال هستند:

این APIها باید در داشبورد API پروژه شما فهرست شوند.

برای اطلاعات بیشتر در مورد فعال کردن و غیرفعال کردن APIها اینجا را کلیک کنید.

پیکربندی Genkit

برای فعال کردن Cloud Tracing، Logging و Monitoring (سنجش ها)، کافی است با enableGoogleCloudTelemetry() تماس بگیرید:

import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';

enableGoogleCloudTelemetry();

هنگام اجرا در تولید، تله متری به طور خودکار صادر می شود.

احراز هویت و مجوز

این افزونه به شناسه پروژه Google Cloud و اعتبار برنامه نیاز دارد.

Google Cloud

در صورت استقرار کد خود در یک محیط Google Cloud (توابع Cloud، Cloud Run و غیره)، شناسه پروژه و اعتبارنامه ها به طور خودکار از طریق Application Default Credentials کشف می شوند.

شما باید نقش‌های زیر را برای حساب سرویسی که کد شما را اجرا می‌کند (یعنی «حساب سرویس پیوست شده») از طریق کنسول IAM اعمال کنید:

  • roles/monitoring.metricWriter
  • roles/cloudtrace.agent
  • roles/logging.logWriter

توسعه محلی

هنگام انجام توسعه محلی، برای اینکه اعتبار کاربری شما در دسترس افزونه باشد، مراحل بیشتری لازم است.

  1. متغیر محیطی GCLOUD_PROJECT را روی پروژه Google Cloud خود تنظیم کنید.

  2. با استفاده از gcloud CLI احراز هویت:

    gcloud auth application-default login

محیط های تولید خارج از Google Cloud

در صورت امکان، همچنان توصیه می‌شود از فرآیند اعتبارنامه پیش‌فرض برنامه برای در دسترس قرار دادن اعتبارنامه‌ها برای افزونه استفاده کنید.

معمولاً این شامل ایجاد یک کلید/جفت حساب سرویس و استقرار آن اعتبارنامه ها در محیط تولید شما است.

  1. دستورالعمل ها را برای تنظیم کلید حساب سرویس دنبال کنید.

  2. مطمئن شوید که حساب سرویس دارای نقش های زیر است:

    • roles/monitoring.metricWriter
    • roles/cloudtrace.agent
    • roles/logging.logWriter

  3. استقرار فایل اعتبارنامه برای تولید (در کد منبع بررسی نکنید )

  4. متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را به عنوان مسیر فایل اعتبارنامه تنظیم کنید.

    GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"

در برخی از محیط‌های بدون سرور، ممکن است نتوانید یک فایل اعتباری را مستقر کنید. در این مورد، به عنوان جایگزینی برای مراحل 3 و 4 بالا، می توانید متغیر محیطی GCLOUD_SERVICE_ACCOUNT_CREDS را با محتوای فایل اعتبارنامه به صورت زیر تنظیم کنید:

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-ath تعیین کنید.

نمونه بردار

برای مواردی که صادرات همه ردیابی ها عملی نیست، OpenTelemetry اجازه نمونه برداری از ردیابی را می دهد.

چهار نمونه از پیش تنظیم شده وجود دارد:

  • AlwaysOnSampler - از همه ردیابی ها نمونه برداری می کند
  • AlwaysOffSampler - نمونه برداری بدون ردیابی
  • ParentBased - نمونه‌ها بر اساس فاصله والدین
  • TraceIdRatioBased - درصد قابل تنظیمی از ردیابی ها را نمونه برداری می کند

autoInstrumentation & autoInstrumentationConfig

فعال کردن ابزار دقیق خودکار به OpenTelemetry اجازه می دهد تا داده های تله متری را از کتابخانه های شخص ثالث بدون نیاز به تغییر کد ضبط کند.

metricExportIntervalMillis

این فیلد فاصله صادرات معیارها را بر حسب میلی ثانیه مشخص می کند.

metricExportTimeoutMillis

این فیلد مدت زمان خروج معیارها را بر حسب میلی ثانیه مشخص می کند.

غیرفعال کردن متریک

نادیده گرفتنی را ارائه می دهد که صادرات معیارها را غیرفعال می کند و در عین حال ردیابی ها و گزارش ها را صادر می کند.

غیرفعال کردن Traces

نادیده گرفتنی را ارائه می‌کند که در حین استخراج معیارها و گزارش‌ها، صادرات ردیابی را غیرفعال می‌کند.

غیرفعال کردن LoggingInputAndOutput

یک نادیده گرفته می شود که جمع آوری گزارش های ورودی و خروجی را غیرفعال می کند.

forceDevExport

این گزینه Genkit را مجبور می کند که داده های تله متری و گزارش را هنگام اجرا در محیط dev (مثلاً به صورت محلی) صادر کند.

ادغام خود را تست کنید

هنگام پیکربندی افزونه، از forceDevExport: true برای فعال کردن صادرات تله متری برای اجراهای محلی استفاده کنید. برای مشاهده تله متری به Google Cloud Logs، Metrics یا Trace Explorer بروید.

مجموعه Google Cloud Observability

هنگامی که کد شما (به عنوان مثال جریان) مستقر شد، به داشبورد Cloud Monitoring بروید و پروژه خود را انتخاب کنید. از اینجا می توانید به راحتی بین کاوشگرهای Logs، Metrics و Trace برای نظارت بر تولید حرکت کنید.

سیاههها و آثار

از منوی سمت چپ، روی «کاوشگر گزارش‌ها» در زیر عنوان «کاوش» کلیک کنید.

در اینجا، همه گزارش‌هایی را خواهید دید که با کد Genkit مستقر شده شما مرتبط هستند، از جمله console.log() . هر گزارشی که دارای پیشوند [genkit] باشد یک گزارش داخلی Genkit است که حاوی اطلاعاتی است که ممکن است برای اهداف اشکال زدایی جالب باشد. برای مثال، گزارش‌های Genkit در قالب Config[...] حاوی ابرداده‌هایی مانند دما و مقادیر topK برای استنتاج‌های خاص LLM هستند. گزارش‌ها در قالب Output[...] حاوی پاسخ‌های LLM هستند در حالی که گزارش‌های Input[...] حاوی اعلان‌ها هستند. Cloud Logging دارای ACL های قوی است که به کنترل دقیق دسترسی به گزارش های حساس اجازه می دهد.

این یک صفحه پیش نمایش ردیابی را نشان می دهد که یک نگاه سریع به جزئیات ردیابی ارائه می دهد. برای دسترسی به جزئیات کامل، روی پیوند "View in Trace" در سمت راست بالای صفحه کلیک کنید.

برجسته ترین عنصر ناوبری در Cloud Trace نمودار پراکندگی ردیابی است. این شامل تمام آثار جمع آوری شده در یک بازه زمانی معین است.

با کلیک بر روی هر نقطه داده، جزئیات آن در زیر نمودار پراکندگی نشان داده می شود.

نمای دقیق شامل شکل جریان، از جمله تمام مراحل، و اطلاعات مهم زمان بندی است. Cloud Trace این قابلیت را دارد که همه گزارش‌های مرتبط با یک ردیابی معین را در این نما به هم متصل کند. در منوی کشویی «Logs & Events» گزینه «Show expanded» را انتخاب کنید.

نمای حاصل امکان بررسی دقیق گزارش‌ها را در زمینه ردیابی، از جمله درخواست‌ها و پاسخ‌های LLM فراهم می‌کند.

معیارها

مشاهده تمام معیارهای صادر شده توسط Genkit را می توان با کلیک بر روی "مدیریت معیارها" در زیر عنوان "پیکربندی" در منوی سمت چپ انجام داد.

کنسول مدیریت متریک شامل نمای جدولی از تمام معیارهای جمع آوری شده، از جمله مواردی است که مربوط به Cloud Run و محیط اطراف آن است. با کلیک بر روی گزینه "Workload" لیستی نشان داده می شود که شامل معیارهای جمع آوری شده توسط Genkit است. هر متریک با پیشوند genkit یک معیار Genkit داخلی را تشکیل می دهد.

Genkit چندین دسته از معیارها را جمع آوری می کند، از جمله: ویژگی، اقدام، و تولید. هر معیار دارای چندین بعد مفید است که فیلتر کردن و گروه بندی قوی را تسهیل می کند.

ابعاد متداول عبارتند از:

  • flow_name - نام سطح بالای جریان.
  • flow_path - دهانه و زنجیره دهانه والد آن تا دهانه ریشه.
  • error_code - در صورت بروز خطا، کد خطای مربوطه.
  • error_message - در صورت بروز خطا، پیام خطای مربوطه.
  • model - نام مدل.

معیارهای ویژگی

ویژگی ها نقطه ورود سطح بالایی به کد Genkit شما هستند. در بیشتر موارد، این یک جریان خواهد بود. در غیر این صورت، این بالاترین فاصله در یک ردیابی خواهد بود.

نام تایپ کنید توضیحات
genkit/ویژگی/درخواست‌ها شمارنده تعداد درخواست ها
genkit/ویژگی/تأخیر هیستوگرام تأخیر اجرا در ms

هر معیار ویژگی شامل ابعاد زیر است:

نام توضیحات
نام نام ویژگی. در بیشتر موارد، این جریان Genkit در سطح بالا است
وضعیت "موفقیت" یا "شکست" بسته به اینکه آیا درخواست ویژگی موفق بوده است یا خیر
خطا تنظیم فقط زمانی که status=failure . حاوی نوع خطایی است که باعث خرابی شده است
منبع زبان مبدأ Genkit. به عنوان مثال 'ts'
منبع نسخه نسخه فریمورک Genkit

معیارهای اقدام

اقدامات نشان دهنده یک مرحله کلی از اجرا در Genkit است. هر یک از این مراحل معیارهای زیر را ردیابی خواهند کرد:

نام تایپ کنید توضیحات
جنکیت/عمل/درخواست شمارنده تعداد دفعاتی که این عمل اجرا شده است
genkit/action/latency هیستوگرام تأخیر اجرا در ms

هر معیار کنش شامل ابعاد زیر است:

نام توضیحات
نام نام عمل
نام ویژگی نام ویژگی والد در حال اجرا
مسیر مسیر اجرا از ریشه ویژگی تا این اکشن. به عنوان مثال '/myFeature/parentAction/thisAction'
وضعیت "موفقیت" یا "شکست" بسته به اینکه آیا عمل موفق بوده است یا خیر
خطا تنظیم فقط زمانی که status=failure . حاوی نوع خطایی است که باعث خرابی شده است
منبع زبان مبدأ Genkit. به عنوان مثال 'ts'
منبع نسخه نسخه فریمورک Genkit

تولید معیارها

اینها معیارهای اقدام ویژه مربوط به اقداماتی هستند که با یک مدل تعامل دارند. علاوه بر درخواست‌ها و تأخیر، ورودی و خروجی نیز با ابعاد خاص مدل ردیابی می‌شوند که اشکال‌زدایی و تنظیم پیکربندی را آسان‌تر می‌کند.

نام تایپ کنید توضیحات
genkit/ai/generate/درخواست شمارنده تعداد دفعاتی که این مدل فراخوانی شده است
genkit/ai/generate/latency هیستوگرام تأخیر اجرا در ms
genkit/ai/generate/input/tokens شمارنده توکن های ورودی
genkit/ai/generate/output/tokens شمارنده توکن های خروجی
genkit/ai/generate/input/character شمارنده کاراکترهای ورودی
genkit/ai/generate/output/character شمارنده کاراکترهای خروجی
genkit/ai/generate/input/images شمارنده تصاویر ورودی
genkit/ai/generate/output/images شمارنده خروجی تصاویر
genkit/ai/generate/input/audio شمارنده فایل های صوتی را وارد کنید
genkit/ai/generate/output/audio شمارنده خروجی فایل های صوتی

هر معیار تولید شامل ابعاد زیر است:

نام توضیحات
نام مدل نام مدل
نام ویژگی نام ویژگی والد در حال اجرا
مسیر مسیر اجرا از ریشه ویژگی تا این اکشن. به عنوان مثال '/myFeature/parentAction/thisAction'
تاخیر خانم ها زمان پاسخگویی که توسط مدل گرفته شده است
وضعیت "موفقیت" یا "شکست" بسته به اینکه آیا درخواست ویژگی موفق بوده است یا خیر
خطا تنظیم فقط زمانی که status=failure . حاوی نوع خطایی است که باعث خرابی شده است
منبع زبان مبدأ Genkit. به عنوان مثال 'ts'
منبع نسخه نسخه فریمورک Genkit

تجسم معیارها را می توان از طریق Metrics Explorer انجام داد. با استفاده از منوی سمت چپ، روی «کاوشگر متریک» در زیر عنوان «کاوش» کلیک کنید.

با کلیک بر روی منوی بازشوی «انتخاب یک معیار»، انتخاب «گره عمومی»، «Genkit» و یک معیار، یک معیار را انتخاب کنید.

تجسم متریک به نوع آن (شمارگر، هیستوگرام و غیره) بستگی دارد. Metrics Explorer امکانات جمع آوری و پرس و جو قوی را برای کمک به نمودارهای معیارها بر اساس ابعاد مختلف آنها فراهم می کند.

تاخیر در تله متری

ممکن است قبل از نمایش تله متری برای اجرای خاصی از یک جریان در مجموعه عملیات Cloud کمی تأخیر وجود داشته باشد. در بیشتر موارد، این تاخیر کمتر از 1 دقیقه است.

سهمیه ها و محدودیت ها

چند سهمیه وجود دارد که باید در نظر داشت:

هزینه

Cloud Logging، Cloud Trace و Cloud Monitoring دارای سطوح سخاوتمندانه رایگان هستند. قیمت های ویژه را می توانید در لینک های زیر مشاهده کنید: