הפלאגין של Google Cloud

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

התקנה

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,‏ 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.

צריך להחיל את התפקידים הבאים על חשבון השירות שבו פועל הקוד (כלומר 'חשבון השירות המצורף') דרך מסוף IAM:

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

פיתוח מקומי

כשמבצעים פיתוח מקומי, צריך לבצע שלבים נוספים כדי שפרטי הכניסה של המשתמש יהיו זמינים לתוסף.

  1. מגדירים את משתנה הסביבה GCLOUD_PROJECT לפי הפרויקט שלכם ב-Google Cloud.

  2. אימות באמצעות ה-CLI של gcloud:

    gcloud auth application-default login

סביבות ייצור מחוץ ל-Google Cloud

אם אפשר, עדיין מומלץ להשתמש בתהליך של Application Default Credentials כדי להפוך את פרטי הכניסה לזמינים לתוסף.

בדרך כלל, התהליך כולל יצירת מפתח או זוג מפתחות של חשבון שירות ופריסה של פרטי הכניסה האלה בסביבת הייצור.

  1. פועלים לפי ההוראות כדי להגדיר מפתח לחשבון שירות.

  2. מוודאים שלחשבון השירות יש את התפקידים הבאים:

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

  3. פורסים את קובץ פרטי הכניסה בסביבת הייצור (לא מוסיפים אותו לקוד המקור)

  4. מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS כנתיב לקובץ פרטי הכניסה.

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

בסביבות ללא שרת, יכול להיות שלא תוכלו לפרוס קובץ פרטי כניסה. במקרה כזה, אפשר להגדיר את משתנה הסביבה GCLOUD_SERVICE_ACCOUNT_CREDS באמצעות תוכן קובץ פרטי הכניסה באופן הבא, במקום לבצע את שלבים 3 ו-4 שלמעלה:

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 כדי להציג את הנתונים הטלמטריםיים.

חבילת Google Cloud Observability

אחרי הפריסה של הקוד (למשל תהליך), עוברים למרכז הבקרה של Cloud Monitoring ובוחרים את הפרויקט. מכאן אפשר לנווט בקלות בין חלונות הניתוחים Logs,‏ Metrics ו-Trace למעקב בסביבת הייצור.

יומנים ומעקב

בתפריט הימני, לוחצים על 'כלי הניווט ביומני' בקטע 'ניתוח'.

כאן יוצגו כל היומנים שמשויכים לקוד Genkit שנפרס, כולל console.log(). כל יומן עם הקידומת [genkit] הוא יומן פנימי של Genkit שמכיל מידע שעשוי להיות מעניין למטרות ניפוי באגים. לדוגמה, יומני Genkit בפורמט Config[...] מכילים מטא-נתונים כמו הטמפרטורה וערכים של topK להסקות ספציפיות של LLM. יומנים בפורמט Output[...] מכילים תגובות LLM, בעוד שיומני Input[...] מכילים את ההנחיות. ב-Cloud Logging יש רשימות ACL חזקות שמאפשרות לשלוט באופן פרטני בגישה ליומנים רגישים.

תוצג חלונית תצוגה מקדימה של המעקב, שבה תוכלו לראות את הפרטים של המעקב במבט מהיר. כדי להגיע לפרטים המלאים, לוחצים על הקישור 'הצגה ב-Trace' בפינה השמאלית העליונה של החלונית.

רכיב הניווט הבולט ביותר ב-Cloud Trace הוא תרשים הפיזור של המעקב. הוא מכיל את כל העקבות שנאספו בפרק זמן נתון.

לחיצה על כל נקודת נתונים תציג את הפרטים שלה מתחת לתרשים הפיזור.

התצוגה המפורטת מכילה את צורת התהליך, כולל כל השלבים, ומידע חשוב על תזמון. ב-Cloud Trace יש אפשרות לשלב בין כל היומנים שמשויכים למעקב נתון בתצוגה הזו. בוחרים באפשרות 'הצגה מורחבת' בתפריט הנפתח 'יומנים ואירועים'.

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

מדדים

כדי להציג את כל המדדים שיוצאו על ידי Genkit, לוחצים על 'ניהול מדדים' בקטע 'הגדרה' בתפריט הימני.

מסוף ניהול המדדים מכיל תצוגה טבלאית של כל המדדים שנאספו, כולל אלה שקשורים ל-Cloud Run ולסביבתו. לחיצה על האפשרות 'עומס עבודה' תציג רשימה שכוללת מדדים שנאספו על ידי Genkit. כל מדד עם הקידומת genkit הוא מדד פנימי של Genkit.

Genkit אוסף כמה קטגוריות של מדדים, כולל: תכונה, פעולה ויצירה. לכל מדד יש כמה מאפיינים שימושיים שמאפשרים סינון וקיבוץ יעילים.

דוגמאות למאפיינים נפוצים:

  • flow_name – השם ברמה העליונה של התהליך.
  • flow_path – ה-span ו-span ההורה שלו נקשרים עד ל-span ברמה הבסיסית.
  • error_code – במקרה של שגיאה, קוד השגיאה התואם.
  • error_message – במקרה של שגיאה, הודעת השגיאה המתאימה.
  • model – שם המודל.

מדדי פיצ'רים

התכונות הן נקודת הכניסה ברמה העליונה לקוד של Genkit. ברוב המקרים, זה יהיה תהליך. אחרת, זה יהיה ה-span העליון ביותר במעקב.

שם סוג תיאור
genkit/feature/requests מונה מספר הבקשות
genkit/feature/latency היסטוגרמה זמן האחזור של ההרצה באלפיות השנייה

כל מדד של תכונה מכיל את המאפיינים הבאים:

שם תיאור
שם שם התכונה. ברוב המקרים, זהו תהליך Genkit ברמה העליונה
סטטוס 'success' או 'failure', בהתאם להצלחה או לכישלון של בקשת התכונה
error מוגדר רק כש-status=failure. מכיל את סוג השגיאה שגרמה לכשל
source שפת המקור של Genkit. למשל 'ts'
sourceVersion גרסת ה-framework של Genkit

מדדי פעולה

פעולות מייצגות שלב כללי של ביצוע ב-Genkit. בכל אחד מהשלבים האלה יתבצע מעקב אחרי המדדים הבאים:

שם סוג תיאור
genkit/action/requests מונה מספר הפעמים שהפעולה בוצעה
genkit/action/latency היסטוגרמה זמן האחזור של ההרצה באלפיות השנייה

כל מדד של פעולה מכיל את המאפיינים הבאים:

שם תיאור
שם שם הפעולה
featureName השם של תכונת ההורה שמופעלת
נתיב נתיב ההרצה מהשורש של התכונה אל הפעולה הזו. לדוגמה: ‎'/myFeature/parentAction/thisAction'‎
סטטוס 'success' או 'failure', בהתאם להצלחה או לכישלון של הפעולה
error מוגדר רק כש-status=failure. מכיל את סוג השגיאה שגרמה לכשל
source שפת המקור של Genkit. למשל 'ts'
sourceVersion גרסת ה-framework של Genkit

יצירת מדדים

מדדים מיוחדים של פעולות שקשורים לפעולות שמקיימות אינטראקציה עם מודל. בנוסף לבקשות ולזמן האחזור, מתבצע גם מעקב אחרי הקלט והפלט, עם מאפיינים ספציפיים למודל שמקלים על ניפוי באגים ועל שינוי ההגדרות.

שם סוג תיאור
genkit/ai/generate/requests מונה מספר הפעמים שהמודל הזה הופעל
genkit/ai/generate/latency היסטוגרמה זמן האחזור של ההרצה באלפיות השנייה
genkit/ai/generate/input/tokens מונה טוקני קלט
genkit/ai/generate/output/tokens מונה טוקני פלט
genkit/ai/generate/input/characters מונה הזנת תווים
genkit/ai/generate/output/characters מונה תווים בפלט
genkit/ai/generate/input/images מונה תמונות קלט
genkit/ai/generate/output/images מונה תמונות פלט
genkit/ai/generate/input/audio מונה קלט קובצי אודיו
genkit/ai/generate/output/audio מונה קובצי אודיו של פלט

כל מדד יצירת נתונים מכיל את המאפיינים הבאים:

שם תיאור
modelName שם הדגם
featureName השם של תכונת ההורה שמופעלת
נתיב נתיב ההרצה מהשורש של התכונה אל הפעולה הזו. לדוגמה: ‎'/myFeature/parentAction/thisAction'‎
latencyMs זמן התגובה של המודל
סטטוס 'success' או 'failure', בהתאם להצלחה או לכישלון של בקשת התכונה
error מוגדר רק כש-status=failure. מכיל את סוג השגיאה שגרמה לכשל
source שפת המקור של Genkit. למשל 'ts'
sourceVersion גרסת ה-framework של Genkit

אפשר להציג את המדדים באופן חזותי באמצעות Metrics Explorer. בתפריט שמשמאל, לוחצים על 'כלי הניתוחים של המדדים' בקטע 'ניתוח'.

כדי לבחור מדד, לוחצים על התפריט הנפתח 'בחירת מדד', בוחרים באפשרות 'Generic Node' (צומת גנרי), 'Genkit' (Genkit) ומדד.

התצוגה החזותית של המדד תלויה בסוג שלו (מספר, תרשים היסטוגרמה וכו'). ב-Metrics Explorer יש כלי יעילים לצבירה ולשליחת שאילתות, שבעזרתם אפשר להציג מדדים בתרשים לפי המאפיינים השונים שלהם.

עיכוב בטלמטריה

יכול להיות עיכוב קל עד שהנתונים הטלמטרים של ביצוע מסוים של תהליך יוצגו בחבילת הכלים לניהול ב-Cloud. ברוב המקרים, העיכוב הוא פחות מדקה.

מכסות ומגבלות

יש כמה מכסות שחשוב לזכור:

עלות

ל-Cloud Logging, ל-Cloud Trace ול-Cloud Monitoring יש רמות חינמיות נדיבות. מחירים ספציפיים זמינים בקישורים הבאים: