מעקב אחר התנועה דרך Agent Gateway

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

Cloud Logging

היומנים של Agent Gateway נוצרים באמצעות המשאב במעקב networkservices.googleapis.com/Gateway.

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

הצגת יומנים של שער ספציפי

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

שאילתה במסוף

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

    כניסה לדף Logs Explorer

  2. לוחצים על המתג Show query.

  3. מדביקים את הטקסט הבא בשדה השאילתה.

    resource.type="networkservices.googleapis.com/Gateway"
resource.labels.location="REGION"
resource.labels.gateway_name="AGENT_GATEWAY_NAME"

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

    • ‫REGION: האזור של השער.
    • ‫AGENT_GATEWAY_NAME: שם השער.

  4. לוחצים על Run query.

שמות היומנים ב-Agent Platform

כדי לשלוח שאילתות על סוגים ספציפיים של רשומות ביומן ב-Logs Explorer, אתם יכולים לסנן את השאילתה לפי שם היומן באמצעות השדה logName. בטבלה הבאה מתוארים שמות היומנים הראשיים שנוצרים על ידי Agent Gateway והפעולות בצד הסוכן:

שם יומן הביקורת תיאור
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests יומנים של החלטות לאשר או לדחות בשער.
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access יומני ביקורת ב-Cloud להחלטות של שרת proxy לאימות זהויות (IAP) AuthorizeUser.
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr שגיאות הפעלה והרצה בצד של הסוכן (מנוע חשיבה רציונלית stderr).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout פלט סטנדרטי (stdout) בצד של הסוכן (מנוע חשיבה רציונלית stdout).

מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud .

אם אתם משתמשים ב-Model Armor כדי להסיר תוכן זדוני או רגיש, היומנים האלה נשלחים בנפרד. הוראות לשליחת שאילתות ביומנים של Model Armor מופיעות במאמר הצגת יומני אבטחה של תוכן גולמי ב-Logs Explorer.

מה מתועד ביומן

רשומות ביומן של Agent Gateway מכילות מידע שימושי למעקב אחרי התנועה אל שער הגישה וממנו, ולניפוי באגים.

שדה פורמט השדה סוג השדה: חובה או אופציונלי תיאור
severity
insertID
timestamp
receiveTimestamp
trace
traceSampled
logName		 LogEntry חובה השדות הכלליים שמתוארים ברשומת יומן.
httpRequest HttpRequest חובה פרוטוקול נפוץ לרישום בקשות HTTP ביומן.
משאב MonitoredResource חובה

‫MonitoredResource הוא סוג המשאב שמשויך לרשומה ביומן. סוג המשאב של Agent Gateway הוא networkservices.googleapis.com/Gateway.
jsonPayload אובייקט (פורמט Struct) חובה

המטען הייעודי (payload) של הרשומה ביומן, שמיוצג כאובייקט JSON. אובייקט ה-JSON מכיל את השדות הבאים של Agent Gateway:

  • ‫agentGatewayInfo: כולל מידע על בקשות של Agent Gateway.

    • ‫mcpInfo: כולל מידע על ה-method של פרוטוקול MCP בבקשה (לדוגמה, "tools/list" או "tools/call") ועל הפרמטר הראשי שמשויך ל-method, אם יש כזה. לדוגמה, ב-method‏ "tools/call", הפרמטר הוא שם הכלי.
    • ‫agentRegistryResource: שם המשאב ב-Agent Registry של שרת ה-MCP, הנציג או נקודת הקצה שהותאמו לבקשה.

  • אפשר גם לבדוק את הפרטים בשדה serviceExtensionsInfo כדי לקבל מידע על התוסף שמפנה לבדיקת הרשאות (IAP, הגנה מוגברת על המודל או אחר) שטיפל בבקשה.

Cloud Monitoring

‫Agent Gateway מייצא ל-Monitoring חלק מהמדדים של Service Extensions. אם אתם מאצילים הרשאות לתוספי שירות, אתם יכולים להשתמש במדדים האלה כדי לעקוב אחרי התנועה אל התוסף וממנו. לפרטים נוספים, קראו את המאמר רישום ביומן ומעקב אחרי קריאות ל- Cloud Load Balancing.

לוח הבקרה של ניראות (observability)

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

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

כדי לגשת למרכז הבקרה של יכולת התצפית של שער במסוף Google Cloud :

  1. נכנסים לדף Agent Gateway במסוף Google Cloud .

    כניסה ל-Agent Gateway

  2. לוחצים על שם השער שרוצים לעקוב אחריו.

  3. לוחצים על הכרטיסייה Observability.

הדרישות לגבי הנתונים במרכז הבקרה

לוח הבקרה של Agent Gateway משתמש ב-Observability Analytics כדי להציג נתונים. אם הנתונים לא נטענים במרכז הבקרה, ודאו ששדרגתם את קטגוריית היומנים _Default כדי להשתמש ב-Observability Analytics. מרכז הבקרה מאחזר נתונים מהתצוגה _AllLogs של הקטגוריה _Default.

שימוש ב-Cloud Trace

‫Agent Gateway משתלב עם Cloud Trace כדי לספק יכולת תצפית מקצה לקצה על בקשות לעומסי עבודה של סוכנים. ‫Agent Gateway משמש כנקודת הבקרה המרכזית של סוכני ה-AI, ולכן הפעלת Trace מאפשרת לכם לראות איך הבקשות עוברות מהסוכנים דרך השער, ובין כמה שירותים, כלים, סוכנים ושרתי MCP ב- Google Cloud . באמצעות מעקב אחרי זרימת הבקשות בין גבולות השירות האלה, Trace מספק מעקב מבוזר מלא לארכיטקטורות של הסוכנים.

בעזרת Trace אתם יכולים:

  • ניפוי באגים מדויק באינטראקציות של הנציג: מעקב אחרי המסלול המלא של בקשה בין גבולות השירות כדי לבודד צווארי בקבוק של זמן אחזור וקריאות לקצה העורפי שנכשלו.
  • החלטות לגבי דגימה במעלה הזרם: משתמשים בדגימה מבוססת-הורה כדי לשמור על רציפות המעקב מקצה לקצה כשסוכנים או לקוחות במעלה הזרם מתחילים את המעקב, וכך לוודא שבקשות בעדיפות גבוהה מתועדות במלואן בלי להגדיל את שיעורי הדגימה הבסיסיים לתנועה רגילה.
  • תצפיתיות אחידה עם תקנים פתוחים: המערכת מבוססת על תקני OpenTelemetry ו-W3C TraceContext, כך שהמעקבים מעבירים את ההקשר בצורה חלקה בין סוכני ה-AI,‏ Agent Gateway, שרתי או כלי ה-MCP המטורגטים ופלטפורמות מעקב של צד שלישי.
  • ניתוח מהיר יותר של שורש הבעיה: אפשר לקשר בין טווחי המעקב לבין יומני הבקשות והמדדים של השער באמצעות trace_id, כדי לפתור מהר יותר בעיות בסביבת הייצור.

לסקירה הכללית על Cloud Trace

התפקידים הנדרשים

אתם צריכים את התפקידים הבאים של ניהול זהויות והרשאות גישה (IAM) בפרויקט:

  • כדי להגדיר ולעדכן מדיניות מעקב: אדמין של רשת Compute‏ (roles/compute.networkAdmin) או אדמין של Compute‏ (roles/compute.admin)
  • כדי לצפות במעקבים במסוף Google Cloud : משתמש ב-Cloud Trace‏ (roles/cloudtrace.user)

בנוסף, כדי לאפשר ל-Agent Gateway לכתוב טווחי מעקב ב-Trace, צריך לתת את התפקיד Cloud Trace Agent (roles/cloudtrace.agent) לחשבונות השירות הבאים:

  • סוכן השירות של Compute Engine: service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
  • סוכן השירות של אבטחת הרשת: service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
  • סוכן השירות של Agent Gateway: service-PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com
  • חשבון השירות של סוכן ה-AI או של עומס העבודה של הלקוח: אם סוכן ה-AI או עומס העבודה של הלקוח שולחים את הקריאה החוזרת, מתחילים את המעקב ומייצאים את ה-parent spans שלהם ל-Trace, צריך להקצות לחשבון השירות של עומס העבודה או לחשבון השירות בהתאמה אישית שמצורף לסוכן את התפקיד roles/cloudtrace.agent בפרויקט. אחרת, רק ה-span הצאצא של Agent Gateway נכתב, וה-span ההורה חסר ב-Trace.

מחליפים את PROJECT_NUMBER במספר הפרויקט ב- Google Cloud .

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

הפעלת המעקב

כדי להפעיל מעקב ב-Agent Gateway, יוצרים קובץ YAML של מדיניות ניטור ומייבאים אותו באמצעות ה-CLI של gcloud.

  1. יוצרים קובץ תצורה בשם tracing-policy.yaml:

    name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/POLICY_NAME"
telemetryTarget:
  resources: # You can attach a policy to multiple gateways
  - "//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME"
displayName: "Tracing policy for Agent Gateway traffic"
tracingConfiguration:
  samplingRate: SAMPLING_RATE
  parentBasedSampling:
    enabled: ENABLE_PARENT_BASED_SAMPLING
    samplingRate: PARENT_BASED_SAMPLING_RATE

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫REGION: האזור של השער (לדוגמה, europe-west1).
    • ‫POLICY_NAME: שם למדיניות הניטור (לדוגמה, my-agw-tracing-policy).
    • ‫AGENT_GATEWAY_NAME: שם השער.
    • ‫SAMPLING_RATE: החלק של הבקשות למעקב. צריך להגדיר ערך בין 0.0 ל-1.0. בסביבות ייצור עם תנועה גבוהה, מומלץ להגדיר שיעור של 1% (0.01) או 0.1% (0.001) כדי לאזן בין עלויות הניטור וההטמעה.
    • ‫ENABLE_PARENT_BASED_SAMPLING: קובע אם לכבד את הביט שנדגם בכותרות traceparent נכנסות מגורמים במעלה הזרם. מגדירים את הערך true או false.
    • ‫PARENT_BASED_SAMPLING_RATE: החלק של הבקשות שנדגמו מראש למעקב. צריך להגדיר ערך בין 0.0 ל-1.0. לדוגמה, הערך 1.0 דוגם 100% מהבקשות שנדגמו מראש.

  2. מייבאים את מדיניות הניטור:

    gcloud beta network-services telemetry-policies import POLICY_NAME \
   --source=tracing-policy.yaml \
   --location=REGION

הצגת המעקבים

אחרי שמפעילים מעקב מבוזר ושולחים תנועה דרך השער, אפשר לראות את פרטי המעקב במסוף Google Cloud :

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

    כניסה לדף Trace explorer

    אפשר גם למצוא את הדף הזה באמצעות שורת החיפוש.

  2. בסרגל Filter, מזינים ביטוי לסינון המעקב (לדוגמה, סינון לפי סף זמן אחזור, קוד סטטוס של HTTP או URI של בקשה) או מחפשים לפי מזהה המעקב הספציפי.

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

    Trace Explorer

    תצוגת Trace Explorer ב-Trace
    תצוגת Trace explorer ב-Trace

    תצוגת ציר הזמן של המעקב

    תצוגת ציר הזמן ב-Trace
    תצוגת ציר הזמן ב-Trace

    תצוגת תרשים של מעקב

    תצוגת תרשים ב-Trace
    תצוגת תרשים ב-Trace

התאמה בין נתוני מעקב לבין יומנים ומדדים

‫Agent Gateway מספק התאמה חלקה בין נתוני מעקב, יומנים ומדדים:

  • מתאם בין יומן למעקב: כל רשומה ביומן הבקשות של השער שנכתבת ב-Logging מכילה שדה trace בפורמט projects/PROJECT_ID/traces/TRACE_ID.

    • במציג היומנים, לוחצים על רשומת היומן ובוחרים באפשרות View trace details כדי לעבור ישירות לטווח התואם ב-Trace.
    • ב-Trace, לוחצים על Show logs בחלונית Trace Details כדי להציג את כל יומני הבקשות של השער שמשויכים לבקשה הזו.

  • מתאם בין מדדים: השוואה בין קפיצות חדות בזמן האחזור שנצפו במדדי המעקב, כמו networkservices.googleapis.com/agentgateway/total_latencies, לבין פירוט של טווחי המעקב, כדי לזהות אם הקפיצה החדה בזמן האחזור התרחשה בשער או בכלי או בשרת היעד.

פתרון בעיות

בקטע הזה מתוארות בעיות נפוצות והפתרונות שלהן.

  • המעקבים לא מופיעים ב-Cloud Trace:

    1. מוודאים ש-Cloud Trace API‏ (cloudtrace.googleapis.com) מופעל בפרויקט:

      gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID

    2. מוודאים שתפקידי ה-IAM הנדרשים של סוכן Cloud Trace (roles/cloudtrace.agent) הוקצו לכל חשבונות השירות הנדרשים.

    3. מוודאים שמדיניות התצפית קיימת באזור הנכון ושהיא מפנה לשער המתאים של Agent Gateway:

      gcloud beta network-services telemetry-policies describe POLICY_NAME \
    --location=REGION

    4. צריך לבדוק את ה-samplingRate שהוגדר. אם נפח התנועה נמוך או שתדירות הדגימה נמוכה, יכול להיות שהמעקבים לא יתועדו באופן מיידי. כדי לוודא שהמעקב פועל, אפשר לעדכן זמנית את המדיניות כך שתשתמש ב-100% דגימה (samplingRate: 1.00). אל תשכחו לשחזר את קצב הייצור כשתסיימו את הבדיקה.

  • טווחים לא שלמים של מעקב:

    אם קטעי המעקב מופיעים כמעקבי שורש עצמאיים או מנותקים, במקום כקטעי צאצא של בקשות האפליקציה, בצעו את הפעולות הבאות:

    1. מוודאים שההגדרה parentBasedSampling מופעלת (מוגדרת כ-true) במדיניות התצפיתיות.
    2. מוודאים שלסוכן ה-AI או לחשבון השירות של עומס העבודה ששולח את הקריאה החוזרת הוקצה התפקיד "סוכן Cloud Trace" (roles/cloudtrace.agent) בפרויקט, כדי שאפשר יהיה לייצא את הטווחים הראשיים ל-Trace.
    3. מוודאים שהאפליקציה משתמשת ב-OpenTelemetry SDK שמופעלת בו הפצת הקשר של מעקב מבוזר, כדי שכותרת ה-traceparent של W3C תופץ בין גבולות השירות. מידע נוסף זמין במסמכי התיעוד של OpenTelemetry בנושא מפיץ ההקשר TraceContext.

המאמרים הבאים

Codelab

איך מנהלים עומסי עבודה של סוכנים באמצעות Agent Gateway ב-Gemini Enterprise Agent Platform.

פתרון בעיות

איך פותרים בעיות בקישוריות של Agent Gateway.