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

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

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

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

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

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

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

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

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

• אפליקציית אינטרנט קיימת של Gemini Enterprise. למידע על יצירת אפליקציה חדשה, ראו יצירת אפליקציה.

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

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

שמירת נתונים

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

גישה למעקבים בכלי Trace Explorer

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

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

   כניסה לדף Trace Explorer

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

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

   הערה: למידע נוסף על השימוש ב-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.
• מאפיינים מותאמים אישית: שאילתה לפי מאפיין gemini_enterprise.assist_token בטווחים execute_tool או invoke_connector כדי למפות אסימוני עזרה מדור קודם ברמת התור למפל של W3C trace.
• מאפייני משאבים: כל טווח מיוצא מכיל את cloud.region,
• מאפייני משאבים: כל span שמיוצא כולל את המאפיין cloud.region. המאפיין הזה מייצג את המיקום של שרת Gemini Enterprise שטיפל בבקשה, למשל global,‏ us או eu. אפשר לסנן לפי המאפיין הזה כדי להשוות בין הביצועים באזורים שונים. ההשוואה הזו שימושית אם מחבר נתונים מצליח במיקום אחד אבל נכשל במיקום אחר. הערך הזה מייצג את המיקום שבו האפליקציה פועלת, ולא את האזור שבו מתארח מקור הנתונים של הצד השלישי. כדי להחיל את המסנן הזה, קראו את המאמר החלת מסנני span.

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

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

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

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

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

טבלת סיכום המעקבים

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

• סטטוס: הסטטוס הנוכחי של המעקב (כרגע מוצג לא מוגדר).
• ‫Trace span ID: המזהה הייחודי של הטווח של המעקב. לוחצים על הקישור של מזהה ה-span כדי להציג את הפרטים שלו.
• ‫Span Name: תיאור קצר של העבודה שמתבצעת ב-span. דוגמאות לטווחים של מחברי נתונים של Gemini Enterprise:
  • ‫execute_tool <tool_name>: נשלח במהלך שכבת שליחת הכלים ב-Agent Runtime של הסוכן (לדוגמה, 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: בקשה מהסוכן למודל שפה גדול.
• ‫Duration: משך הזמן שלוקח להשלים את טווח המעקב (בדקות).
• קלט: נתוני הקלט או ההודעה שנשלחו לטווח, אם יש כאלה.
• פלט: תוצאת הפלט שמוחזרת על ידי הטווח, אם יש כזו.
• שעת התחלה: חותמת הזמן המדויקת שבה התחיל הביצוע של ה-span.

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

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

1. ‫Summary: הצגת המטא-נתונים של קו הבסיס, כולל שעת התחלה, ‏ Duration והמספר הכולל של Spans. אפשר ללחוץ על View in Cloud Trace או לעבור בין לחצני התצוגה Graph ו-Timeline.
2. תצוגות חזותיות: מעבר בין היררכיה גרפית לתצוגת ציר זמן שמציגה את קשרי ההורה-צאצא של כל הטווחים של המעקב.
3. פרטים של טווח זמן נבחר: בוחרים טווח זמן יחיד כדי להציג קטעים מפורטים, שיכולים לכלול:
   • סיכום: מציג את שם ה-span, שירות היעד, מספר ה-spans הכולל עם הפעולה הזו ומשך הזמן הכולל (בשניות).
   • יומנים: אם הוגדרו יומנים, אפשר לראות את פרטי האירועים הרלוונטיים. כדי לעבור ישירות ליומנים הרגילים, לוחצים על הצגת יומנים.
   • הערכה: מציג את תוצאות ההערכה, אם הוגדרו.
   • קלט ופלט: מטענים (payloads) מלאים של בקשות ותגובות.
   • יומנים ואירועים: רשימת האירועים שהתרחשו במהלך ביצוע הטווח הזה.
   • ‫Stacktraces: פרטי השגיאה אם ההרצה של span נכשלת.
   • מטא-נתונים וקישורים: קישורים שמפנים לישויות קשורות ב-Cloud Explorer.
   • מאפיינים: תגי משאבים ופרמטרים נוספים של נראות בצורת מפתח/ערך.

היררכיית הורה-צאצא של span

כשמפעילים מחברי נתונים, קינון של טווחי הורה-צאצא בתוך מעקב 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 כוללים מטא-נתונים עשירים יותר שמבוססים על המוסכמות הסמנטיות של OpenTelemetry ל-AI גנרטיבי. ב-OpenTelemetry, המוסכמות האלה מסווגות כ-Development status. הסטטוס הזה חל על מפרטים בשלבים מוקדמים שיכולים להשתנות או להיות מוסרים, ואין להסתמך עליהם בסביבת הייצור. מכיוון שהמוסכמות האלה עדיין לא יציבות, הטלמטריה הזו של Gemini Enterprise היא ניסיונית. הטווחים האלה כוללים מאפייני gen_ai.* שמתארים את הפעילות של הנציג, המודל והכלי, כמו הפעלה של הנציג והכלי ושלבים של הנחיה ותגובה.

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