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

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

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

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

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

קונספט	תיאור
מעקב	מעקב הוא אוסף של קטעי קוד שמייצגים בקשה או טרנזקציה אחת, כשהיא עוברת דרך שירותים ורכיבים שונים. לדוגמה, מעקב מייצג את כל מחזור החיים של בקשה. זה כולל משתמש ששואל שאלה את העוזר האישי של Gemini Enterprise, את התשובה של העוזר האישי של Gemini Enterprise וכל פעולה שמתבצעת בעקבות התשובה, כמו שליחת אימייל.
Span	טווח הוא יחידת עבודה אחת עם תזמון בתוך מעקב. הוא מייצג פעולה ספציפית, כמו בקשה להפעלת פונקציה, בקשת API או שאילתה למסד נתונים. כל span כולל פרטים כמו זמני ההתחלה והסיום, מזהה ייחודי והקשר שלו ל-spans אחרים. הקשרים האלה יוצרים יחד מעקב.
יומני Span	יומני Span הם הודעות או אירועים בפריסה גמישה עם חותמת זמן, שמשויכים ל-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 באמצעות המסננים, הפרמטרים של השאילתות והמאפיינים הבאים:

• מסננים מרובי מאפיינים:
  • ‫Service: מסננים לפי AssistantService או connectorsexecution כדי לבודד את נתיבי הבקשות של סוכן הפלטפורמה ומחבר הנתונים.
  • Span: מסננים לפי /AssistantService.StreamAssist כדי לאתר את ה-spans של המשתמש ברמה הבסיסית (root), או מחפשים 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 waterfall.
• מאפייני משאבים: כל span שמיוצא כולל את 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: המזהה הייחודי של ה-trace span. לוחצים על הקישור של מזהה ה-span כדי להציג את הפרטים שלו.
• שם ה-span: תיאור קצר של הפעולה שה-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: בקשה מהנציג למודל שפה גדול (LLM).
• ‫Duration: משך הזמן שלוקח להשלים את טווח המעקב (בדקות).
• קלט: נתוני הקלט או ההודעה שנשלחו ל-span, אם יש כאלה.
• פלט: תוצאת הפלט שהוחזרה על ידי ה-span, אם יש כזו.
• שעת התחלה: חותמת הזמן המדויקת שבה התחיל הביצוע של ה-span.

תצוגת מעקב מפורטת

לחיצה על Trace span ID פותחת דף מפורט שכולל:

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

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

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

1. ‫/AssistantService.StreamAssist: טווח פלטפורמת C++‎ ברמה הבסיסית (root) שמתחיל את הבקשה.
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.* שמתארים את הפעילות של הסוכן, המודל והכלי, כמו הפעלה של הסוכן והכלי ושלבים של הנחיה ותגובה.

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