פלאגין לטלמטריה ולרישום ביומן של Google Cloud

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

דרישות מוקדמות

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

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

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

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

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

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

תצורה

כדי לאפשר ייצוא ל-Google Cloud Tracing,‏ Logging ו-Monitoring, מייבאים את החבילה googlecloud ומריצים את Init(). אחרי שמפעילים את Init(), הנתונים הטלמטרים מיוצאים באופן אוטומטי.

import "github.com/firebase/genkit/go/plugins/googlecloud"

if err := googlecloud.Init(
	ctx,
	googlecloud.Config{ProjectID: "your-google-cloud-project"},
); err != nil {
	return err
}

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

  • ForceExport: ייצוא נתוני טלמטריה גם כשהאפליקציה פועלת בסביבת פיתוח (למשל, כשמשתמשים ב-genkit start או ב-genkit flow:run). זוהי דרך מהירה לבדוק את השילוב ולשלוח את האירועים הראשונים למעקב ב-Google Cloud.

    אם משתמשים באפשרות הזו, צריך גם להפוך את פרטי הכניסה ל-Cloud לזמינים באופן מקומי:

    gcloud auth application-default login

  • MetricInterval: האינטרוול, בננו-שניות, שבו ייצא מידע טלמטריה. כברירת מחדל, האורך הוא 60 שניות (60e9 ננו-שניות).

  • LogLevel: רמת החומרה המינימלית של רשומות היומן לייצוא. כברירת מחדל, slog.LevelInfo.

כדי להשתמש בפלאגין, צריך את פרטי הכניסה לפרויקט ב-Google Cloud. אם אתם מריצים את התהליכים מסביבת Google Cloud (Cloud Run וכו'), פרטי הכניסה מוגדרים באופן אוטומטי. כדי לפעול בסביבות אחרות צריך להגדיר את Application Default Credentials.

מעקב אחר ייצור באמצעות חבילת התפעול של Google Cloud

אחרי הפריסה של תהליך, עוברים אל חבילת התפעול של Google Cloud ובוחרים את הפרויקט.

יומנים ומעקב אחר נתונים

בתפריט הצד, מחפשים את 'רישום ביומן' ולוחצים על 'כלי הניווט ביומני Google Cloud'.

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

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

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

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

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

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

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

מדדים

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

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

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

מאפיינים נפוצים כוללים:

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

מדדים ברמת הזרימה

שם מאפיינים
genkit/flow/requests flow_name,‏ error_code,‏ error_message
genkit/flow/latency flow_name

מדדים ברמת הפעולה

שם מאפיינים
genkit/action/requests flow_name,‏ error_code,‏ error_message
genkit/action/latency flow_name

מדדים ברמת היצירה

שם מאפיינים
genkit/ai/generate flow_path,‏ model,‏ temperature,‏ topK,‏ topP,‏ error_code,‏ error_message
genkit/ai/generate/input_tokens traffic_path, מודל, טמפרטורה, topK, topP
genkit/ai/generate/output_tokens flow_path,‏ model,‏ temperature,‏ topK,‏ topP
genkit/ai/generate/input_characters traffic_path, מודל, טמפרטורה, topK, topP
genkit/ai/generate/output_characters flow_path,‏ model,‏ temperature,‏ topK,‏ topP
genkit/ai/generate/input_images traffic_path, מודל, טמפרטורה, topK, topP
genkit/ai/generate/output_images flow_path,‏ model,‏ temperature,‏ topK,‏ topP
genkit/ai/generate/latency flow_path,‏ model,‏ temperature,‏ topK,‏ topP,‏ error_code,‏ error_message

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

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

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

זמן אחזור של טלמטריה

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

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

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

עלות

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