הפלאגין של Google Cloud

הפלאגין של Google Cloud מייצא את נתוני הטלמטריה והיומנים של Firebase Genkit אל חבילת התפעול של Google Cloud, שמפעילה את לוח הבקרה של Firebase AI Monitoring (תצוגה מקדימה פרטית).

התקנה

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

אם רוצים להריץ באופן מקומי תהליכים שמשתמשים בפלאגין הזה, צריך להתקין גם את הכלי Google Cloud CLI.

הגדרת חשבון Google Cloud

כדי להשתמש בפלאגין הזה צריך חשבון Google Cloud (נרשמים אם אין לכם חשבון כזה) ופרויקט ב-Google Cloud.

לפני שמוסיפים את הפלאגין, צריך לוודא שממשקי ה-API הבאים מופעלים בפרויקט:

ממשקי ה-API האלה אמורים להופיע במרכז הבקרה של ה-API של הפרויקט.

כאן אפשר לקרוא מידע נוסף על הפעלה והשבתה של ממשקי API.

הגדרת Genkit

כדי להפעיל את הייצוא ל-Google Cloud Tracing, ל-Cloud Logging ול-Cloud Monitoring, פשוט קוראים ל-enableGoogleCloudTelemetry():

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

enableGoogleCloudTelemetry();

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

אימות

כדי להשתמש בפלאגין, צריך את מזהה הפרויקט ב-Google Cloud ואת פרטי הכניסה לפרויקט ב-Google Cloud. אם אתם מריצים את התהליך מסביבת Google Cloud (Cloud Functions,‏ Cloud Run וכו'), מזהה הפרויקט ופרטי הכניסה מוגדרים באופן אוטומטי.

Application Default Credentials

כדי להריץ את הקוד בסביבות אחרות, צריך להגדיר את משתנה הסביבה GCLOUD_PROJECT בפרויקט ב-Google Cloud ולבצע אימות באמצעות הכלי gcloud:

gcloud auth application-default login

מידע נוסף זמין במסמכי העזרה של Application Default Credentials.

פרטי כניסה לחשבון שירות

אם אתם משתמשים בחשבון שירות ומריצים אותו מחוץ לסביבת 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 library.

סמפלר

במקרים שבהם לא מעשי לייצא את כל הטראסים, OpenTelemetry מאפשר דגימה של טראסים.

יש ארבעה Samplers מוגדרים מראש:

autoInstrumentation ו-autoInstrumentationConfig

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

metricExportIntervalMillis

השדה הזה מציין את מרווח הזמן לייצוא המדדים באלפיות שנייה.

metricExportTimeoutMillis

השדה הזה מציין את זמן הקצאת הזמן לתפוגה של ייצוא המדדים באלפיות השנייה.

disableMetrics

מאפשרת לבטל את הייצוא של המדדים ועדיין לייצא את הטרייסים והיומנים.

disableTraces

מאפשרת לבטל את הייצוא של עקבות תוך המשך הייצוא של מדדים ויומנים.

disableLoggingIO

מאפשרת לבטל את איסוף יומני הקלט והפלט.

forceDevExport

האפשרות הזו תאלץ את Genkit לייצא נתוני טלמטריה ונתוני יומנים כשהיא פועלת בסביבה dev (למשל, באופן מקומי).

בדיקת השילוב

כשמגדירים את הפלאגין, משתמשים ב-forceDevExport: true כדי להפעיל את ייצוא הטלמטריה להרצות מקומיות. כדי להציג את הנתונים הטלמטרים, עוברים אל Google Cloud Logs, ‏ Metrics או Trace Explorer. לחלופין, אפשר לעבור אל לוח הבקרה של Firebase AI Monitoring (תצוגה מקדימה פרטית) כדי לראות תצוגה של טלמטריה שמתאימה ל-AI.