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

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

Cloud Logging

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

אתם יכולים להשתמש ביומנים האלה כדי לעקוב אחרי בקשות גישה לשער. זה כולל את היומנים שנוצרים כשפורסים את Agent Gateway במצב פרימטר לבדיקות. כדי לשלוח שאילתות ליומני הפרות המדיניות של ההרצה היבשה במדיניות הגישה המאוחדת (UAP) של שרת proxy לאימות זהויות (IAP), במדיניות הפיקוח בשפה טבעית, ב-Model Armor וב-VPC Service Controls, וליצור דוח מאוחד של "מה היה נחסם", קראו את המאמר בדיקת הפרות של מדיניות ההרצה היבשה באמצעי הבקרה.

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

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

שאילתה במסוף

  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 להחלטות של 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 ביומן.
resource 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, הגנה מוגברת על המודל או אחר) שטיפל בבקשה.

הפצת מדיניות וזמן אחזור של הטמעת יומנים

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

  • הפצה של מערכת גישה מאוחדת לכללי מדיניות (UAP): עדכונים לכללי UAP שנאכפים על ידי Agent Gateway (כמו הוספת כלל DENY או החלפת iamEnforcementMode מ-"DRY_RUN" ל-"ENFORCE") הם עקביים בסופו של דבר. בדרך כלל, שינויים ישירים במדיניות נכנסים לתוקף תוך 2 דקות, אבל יכול להיות שיעברו 7 דקות או יותר עד שהם יתעדכנו בכל העולם (ראו הפצה של שינויי גישה). יכול להיות שיעברו כמה דקות עד כמה שעות עד שהשינויים בחברות ב-principalSet יסונכרנו.
  • עצירת תנועה במקרה חירום: כללי UAP נבדקים בבדיקות הרשאה חדשות ב-Agent Gateway, ולא מסיימים קונטיינר של נציג או סוגרים בכוח חיבורי סטרימינג שכבר נוצרו. כדי לעצור באופן מיידי סוכן שנפגע או שמתנהג בצורה לא תקינה במהלך אירוע פעיל, צריך למחוק את Agent Runtime של הסוכן או לנתב מחדש את תעבורת הגרסאות שלו, בנוסף להחלת כלל דחייה בשער. הוראות מפורטות זמינות במאמר עצירת חירום וביטול גישה.
  • זמן אחזור של יומנים, מעקבים וממצאים: Agent Gateway בודק את כללי המדיניות של IAP ושל Model Armor באופן סינכרוני בנתיב הבקשה, וכותב רשומות ביומנים של networkservices.googleapis.com/gateway_requests ו-cloudaudit.googleapis.com/data_access (AuthorizeUser) כמעט בזמן אמת (בדרך כלל אפשר לחפש אותן ב-Logs Explorer תוך כמה שניות). גם טווחים של מעקב מבוזר שמיוצאים ל-Trace מופיעים תוך כמה שניות מסיום הטווח, ואילו זיהוי איומים מחוץ לתחום מזיהוי אנומליות אצל סוכנים נבדק באופן אסינכרוני (ראו זמן האחזור של טלמטריה וממצאי אבטחה).

שמירה וייצוא של יומני ביקורת של שערים ל-SIEM

כדי לשמור את החלטות הגישה של Agent Gateway כהוכחה לתאימות שמעידה על שיבוש, וכדי לרכז את המעקב אחרי איומים, אתם יכולים לנעול את הקטגוריות של Logging ולהעביר את היומנים של השער לפלטפורמה של ניהול אבטחת מידע ואירועים (SIEM):

  • שמירה עם זיהוי שינויים (קטגוריות נעולות של יומנים): ניתוב היומנים של networkservices.googleapis.com/gateway_requests ו-cloudaudit.googleapis.com/data_access לקטגוריה מותאמת אישית של Logging עם תקופת שמירה מוגדרת (--retention-days) ונעילה של הקטגוריה באופן סופי (gcloud logging buckets update BUCKET_ID --location=LOCATION --locked) כדי לאכוף אחסון תואם לכתיבה חד-פעמית וקריאה מרובה (WORM). להוראות מפורטות, קראו את המאמר שמירת יומני ביקורת עם אינדיקציה לשינוי.
  • ייצוא ל-SIEM: יוצרים sink ביומן (או sink נצבר ברמת הארגון) עם מסנן הכללה של logName:("networkservices.googleapis.com%2Fgateway_requests" OR "cloudaudit.googleapis.com%2Fdata_access") כדי לייצא באופן רציף החלטות של השער לגבי אישור ודחייה אל Google Security Operations‏ (Google SecOps), אל Pub/Sub (להטמעה ב-SIEM של צד שלישי), אל BigQuery או אל Cloud Storage. במאמר ייצוא יומני ביקורת ל-SIEM מופיעות פקודות ליצירת כיורים ב-CLI של gcloud ודוגמאות למסננים.

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 או עומס העבודה של הלקוח ששולחים את הקריאה החוזרת מתחילים את המעקב ומייצאים את ה-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.

    • ב-Logs Explorer, לוחצים על רשומת היומן ובוחרים באפשרות 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 propagator.

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

Codelab

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

פתרון בעיות

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