גישה לעקבות ולטווחים

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

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

מושגים מרכזיים

בקטע הזה נסביר על מושגים מרכזיים שקשורים ליכולת הצפייה ב-Gemini Enterprise.

קונספט	תיאור
מעקב	trace הוא אוסף של span שמייצג בקשה או טרנזקציה יחידה, כשהיא עוברת דרך שירותים ורכיבים שונים. לדוגמה, trace מייצג את מחזור החיים המלא של בקשה. הנתונים כוללים שאלה שמשתמש שואל את Gemini Enterprise Assistant, את התשובה של Gemini Enterprise Assistant וכל פעולה שמתבצעת בעקבות התשובה, כמו שליחת אימייל.
Span	טווח (span) הוא יחידת עבודה יחידה עם תזמון בתוך עקבות. הוא מייצג פעולה ספציפית, כמו קריאה לפונקציה, בקשת API או שאילתה במסד נתונים. כל יחידה לוגית למעקב כולל פרטים כמו זמני ההתחלה ושעת סיום שלו, מזהה ייחודי והקשר שלו ליחידות לוגיות למעקב אחרות. קשרי הגומלין האלה יוצרים ביחד עקבות.
רישומים של יחידות לוגיות למעקב	יומני טווח הם הודעות או אירועים חופשיים עם חותמת זמן שמשויכים ליחידה לוגית למעקב ספציפית. הם מספקים מידע מפורט לפי הקשר על הביצוע של טווח, ועוזרים למשתמשים לנפות באגים ולהבין את זרימת הבקשה.

לפני שמתחילים

חשוב לוודא שיש לכם את הפריטים הבאים:

• התפקיד אדמין של Gemini Enterprise או התפקיד Google Cloud משתמש של Gemini Enterprise במסוף.

• אפליקציית Gemini Enterprise קיימת. מידע על יצירת אפליקציה חדשה זמין במאמר יצירת אפליקציה.

• כדי לגשת לנתוני מעקב, צריך להיות לכם תפקיד משתמש Cloud Trace (roles/cloudtrace.user).

• מפעילים את הגדרת הנראות Enable instrumentation of OpenTelemetry traces and logs (הפעלת מכשור של מעקבים ויומנים של OpenTelemetry). בהתאם לסוג הסוכן, מפעילים את ההגדרה הזו בהגדרות ברמת האפליקציה (בסוכן Core Assistant) או בכרטיסייה Configuration של הסוכן (בסוכנים שנוצרו על ידי עובדים ב-כלי לתכנון סוכנים ובסוכני Deep Research). מידע נוסף מופיע במאמר בנושא ניהול הגדרות של יכולת תצפית.

שמירת נתונים

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

גישה לנתוני מעקב בכלי Trace Explorer

כדי לגשת לנתוני מעקב ולטווחים באמצעות Trace Explorer:

1. נכנסים לדף Trace Explorer במסוף Google Cloud .

   כניסה לדף Trace Explorer

2. בוחרים את הפרויקט Google Cloud שבו נוצרה אפליקציית Gemini Enterprise. כל טווחי הזמן של הפרויקט מוצגים.

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

   הערה: מידע נוסף על השימוש ב-Trace Explorer זמין במאמר חיפוש של עקבות ובדיקה שלהם.

   

סינון וחיפוש של עקבות

בכלי Trace Explorer של הפרויקט, אפשר לבודד ולנתח את ההרצות של סוכן Gemini Enterprise ומחבר הנתונים באמצעות המסננים, פרמטרים של שאילתות ומאפיינים הבאים:

• מסננים עם היבטים:
  • שירות: אפשר לסנן לפי AssistantService או connectorsexecution כדי לבודד את נתיבי הבקשות של סוכן הפלטפורמה ומחבר הנתונים.
  • ‫Span: מסננים לפי /AssistantService.StreamAssist כדי לאתר את ה-spans של פניות המשתמש ברמת הבסיס, או מחפשים spans של צאצאים כמו execute_tool <tool_name> ו-invoke_connector <connector>.
• חיפוש ישיר של מזהה מעקב: אפשר למצוא מעקבים ישירות באמצעות מזהה המעקב הסטנדרטי של W3C באורך 32 תווים, שאפשר לחלץ מכותרות התגובה x-cloud-trace-context מ-StreamAssist.
• מאפיינים מותאמים אישית: כדי למפות אסימוני עזרה מדור קודם ברמת הפנייה למפל של מעקב W3C, צריך לבצע שאילתה לפי מאפיין gemini_enterprise.assist_token בטווחים execute_tool או invoke_connector.

גישה למעקב אחר סוכנים

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

הערה: הכרטיסייה Traces זמינה לסוכן Core Assistant, לסוכנים שנוצרו על ידי עובדים ב-כלי לתכנון סוכנים ולסוכני Deep Research.

כדי לגשת לנתוני מעקב של סוכן:

1. במסוף Google Cloud , עוברים לאפליקציה ולוחצים על Agents (סוכנים).
2. בוחרים את הסוכן שרוצים לבדוק ולוחצים על הכרטיסייה Traces (עקבות).

טבלת סיכום של נתוני ה-Trace

בטבלה הראשית בכרטיסייה Traces מוצגים הפרטים הבאים לגבי כל יחידה לוגית למעקב:

• סטטוס: הסטטוס הנוכחי של המעקב (כרגע מוצג לא מוגדר).
• ‫Trace span ID: המזהה הייחודי של ה-trace span. לוחצים על הקישור span ID כדי לראות את הפרטים שלו.
• שם הטווח: תיאור קצר של העבודה שהטווח מבצע. דוגמאות לטווחים של מחברי נתונים של Gemini Enterprise:
  • ‫execute_tool <tool_name>: מופק במהלך שכבת ההפצה של כלי זמן הריצה של הסוכן (לדוגמה, execute_tool federated_search).
  • ‫invoke_connector <connector>: נוצר על ידי שכבת הביצוע של המחברים כדי לייצג את לוגיקת הבקשה למחבר הספציפי (לדוגמה, invoke_connector jira או invoke_connector servicenow), שמחליף את טווחי ה-RPC שמוגדרים כברירת מחדל בצד השרת.
• ‫Span Type: סוג ה-span. האפשרויות כוללות:
  • ‫Agent to Tool: הפעלה של כלי חיצוני על ידי הסוכן (נעשה שימוש חוזר בפעולות execute_tool ו-invoke_connector).
  • ‫Invoke Agent: הפעלה של סוכן.
  • ‫Agent to Model: בקשה מהסוכן למודל שפה גדול.
• משך: הזמן שנדרש להשלמת יחידה לוגית למעקב (בדקות).
• קלט: נתוני הקלט או ההודעה שנשלחו ליחידה הלוגית למעקב, אם יש כאלה.
• פלט: תוצאת הפלט שמוחזרת על ידי הטווח, אם יש כזו.
• שעת ההתחלה: חותמת הזמן המדויקת שבה התחילה ההרצה של היחידה הלוגית למעקב.

תצוגה מפורטת של מעקב

לחיצה על מזהה של יחידה לוגית למעקב פותחת דף מפורט עם:

1. סיכום: צפייה במטא-נתונים של בסיס ההשוואה, כולל שעת התחלה, משך ומספר הטווחים הכולל. אפשר ללחוץ על הצגה ב-Cloud Trace או לעבור בין הלחצנים של התצוגות תרשים וציר זמן.
2. תצוגות חזותיות: מעבר בין היררכיה גרפית או תצוגת ציר זמן שבה מוצגים קשרי הורה-צאצא של כל טווחי המעקב.
3. פרטים של יחידה לוגית למעקב נבחרת: בוחרים יחידה לוגית למעקב יחידה כדי להציג קטעים מפורטים, שיכולים לכלול:
   • סיכום: מוצגים שם הטווח, שירות היעד, מספר הטווחים הכולל עם הפעולה הזו והמשך הכולל (בשניות).
   • יומנים: אם הגדרתם את האפשרות הזו, תוכלו לראות פרטים רלוונטיים על האירוע. כדי לעבור ישירות ליומנים רגילים, לוחצים על הצגת יומנים.
   • הערכה: מציג את תוצאות ההערכה, אם הוגדרו.
   • קלט ופלט: מטען ייעודי (payload) מלא של בקשה ותגובה.
   • יומנים ואירועים: רשימת האירועים שהתרחשו במהלך ההרצה של יחידה לוגית למעקב זו.
   • Stacktraces: פרטי שגיאה אם ביצוע של span נכשל.
   • מטא-נתונים וקישורים: קישורים שמפנים לישויות קשורות בכלי לבדיקת משאבים בענן.
   • מאפיינים: תגי משאבים ופרמטרים נוספים של נראות (observability) מסוג מפתח/ערך.

היררכיית טווחים של הורה-צאצא

במהלך ההפעלה של מחברי נתונים, קינון של טווחים מסוג parent-child בתוך מעקב W3C יחיד עוזר לאתר בדיוק את המיקום שבו מתרחשת השהיה או שגיאה:

1. ‫/AssistantService.StreamAssist: טווח C++‎ ברמת הפלטפורמה שמתחיל את הבקשה.
2. ‫invoke_agent core_assistant: טווח ההרצה של הסוכן.
3. ‫execute_tool <tool_name>: טווח הביצוע של הכלי הפעיל (לדוגמה, execute_tool federated_search).
4. ‫invoke_connector <connector_name> (לדוגמה, invoke_connector jira או invoke_connector servicenow): טווח הביצוע של המחברים, שמייצג את מחזור החיים של הבקשה לנקודת הקצה של הצד השלישי.

טלמטריה של מוסכמות סמנטיות ניסיוניות של AI גנרטיבי

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

בנוסף לטלמטריה היציבה, טווח המעקב של Gemini Enterprise כולל מטא-נתונים עשירים יותר שמבוססים על מוסכמות סמנטיות של AI גנרטיבי ב-OpenTelemetry. המוסכמות האלה מסווגות ב-OpenTelemetry כסטטוס פיתוח. הסטטוס הזה חל על מפרטים בשלבים מוקדמים של פיתוח, שיכולים להשתנות או להיות מוסרים, ולכן לא מומלץ להסתמך עליהם בסביבת ייצור. המוסכמות האלה עדיין לא יציבות, ולכן הטלמטריה של Gemini Enterprise היא ניסיונית. הטווחים האלה כוללים מאפייני gen_ai.* שמתארים את הפעילות של הסוכן, המודל והכלי, כמו ביצוע של סוכן וכלי ושלבים של הנחיה ותגובה.

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