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

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

רישום ביומן

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

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

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

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

שאילתה במסוף

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

    כניסה לדף Logs Explorer

  2. לוחצים על המתג הצגת השאילתה.

  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).

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

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

מה נרשם ביומן

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

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

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

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

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

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

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

מעקב

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

לוח הבקרה 'ניראות'

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

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

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

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

    כניסה ל-Agent Gateway

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

  3. לוחצים על הכרטיסייה Observability (יכולת תצפית).

הדרישות לגבי נתונים בלוח הבקרה

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

שימוש ב-Cloud Trace

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

באמצעות Trace, אפשר לבצע את הפעולות הבאות:

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

מידע נוסף על Trace זמין במאמר סקירה כללית על Cloud Trace.

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

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

  • כדי להגדיר ולעדכן מדיניות מעקב: אדמין של רשת מחשוב (roles/compute.networkAdmin) או אדמין מחשוב (roles/compute.admin)
  • כדי להציג עקבות ב Google Cloud מסוף: Cloud Trace User (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 או עומס העבודה של הלקוח שמבצעים את הקריאה יוזמים את המעקב ומייצאים את טווחי האב שלהם אל Trace, צריך להעניק לחשבון השירות של עומס העבודה או לחשבון השירות המותאם אישית שמצורף לסוכן את התפקיד roles/cloudtrace.agent בפרויקט. אחרת, רק טווח הצאצא Agent Gateway ייכתב וטווח האב לא יופיע ב-Trace.

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

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

הפעלת מעקב

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

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

    name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/POLICY_NAME"
targetTelemetry:
  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. נכנסים לדף Trace explorer במסוף Google Cloud :

    כניסה אל Trace explorer

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

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

    מידע נוסף על השימוש בממשק המשתמש של Trace explorer מופיע במאמר איתור עקבות ובדיקתם.

    כלי לבדיקת מעקב

    התצוגה Trace Explorer ב-Cloud Trace
    תצוגת Trace Explorer ב-Trace

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

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

    תצוגת גרף של עקבות

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

הצגת קורלציה בין עקבות לבין יומנים ומדדים

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

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

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

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

פתרון בעיות

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

  • ‫Traces לא מופיעים ב-Cloud Trace:

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

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

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

    3. מוודאים שמדיניות ה-Observability קיימת באזור הנכון ושהיא מתייחסת לשער המתאים של Agent Gateway:

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

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

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

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

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

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

Codelab

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

פתרון בעיות

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