מידע על שאילתות

במסמך הזה מתוארים הרכיבים של שאילתת App Topology והתחביר של השאילתה.

רכיבי שאילתה

שאילתות של App Topology מורכבות מכמה רכיבים:

• צמתים – משאבים שזוהו Google Cloud או משאבים שנרשמו ב-מרכז האפליקציות או ב-Agent Registry. דוגמאות לצמתים:

  • מכונה וירטואלית ב-Compute Engine
  • קובץ אימג' של קונטיינר ב-Artifact Registry
  • נציג
  • התראה ב-Cloud Monitoring
  • אפליקציה, שירות או עומס עבודה במרכז האפליקציות
  • נקודת חולשה

  המשאבים שאפשר לשלוח להם שאילתות תלויים בדומיין שתבחרו. הדומיין SRE כולל את כל המשאבים הנתמכים.

• מאפיינים: מאפיינים של צומת שאפשר להשתמש בהם כדי לדייק שאילתה. לדוגמה, אפשר לשלוח שאילתה לגבי פגיעות עם מזהה CVE ספציפי.

• קצה: קשר מכוון בין שני צמתים.

מבנה השאילתה

בקטע הזה מופיעה סקירה כללית של מבנה השאילתה. פרטים נוספים זמינים במאמרי העזרה של הכלי generate_discovered_resources_topology.

השאילתות משתמשות בתחביר הסינון AIP-160.

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

• שאילתות מתחילות ב-startingNode שמציין צומת שורש.
• אתם מגדירים קשרים עם שורש startingNode באמצעות neighbor. הרכיב neighbor מגדיר צמתים וקצוות מחוברים.
• ‫LabelPropertiesPattern מציין ביטויי התאמה.
  • ‫label_matcher_expr – ביטוי התאמה לתוויות של צמתים או קשתות.
  • ‫property_matcher_expr – ביטוי התאמה לסינון מאפיינים ספציפיים של צומת או קשת.
• אתם מגדירים קשר עם כיוון באמצעות השדה direction.

בדוגמה הבאה מוצגת שאילתה להתראות שמשויכות לעומס העבודה של מרכז האפליקציות foo בפרויקט web-project. הוא גם מראה את השימוש ב-alias כדי לתייג צמתים, וכך קל יותר להתייחס אליהם בביטויים הבאים.

{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
  "name": "generate_discovered_resource_topology",
  "arguments": {
    "name": "projects/web-project/locations/global/discoveredResourcesTopology",
    "topologyDomains": ["projects/web-project/locations/global/domains/SRE"],
    "filter": {
        "startingNode": {
        "alias": "source",
        "labelPropertiesPattern": {
          "labelMatcherExpr": "Base/apphub.googleapis.com/Workload",
          "propertyMatcherExpr": "source.Base/app/workloadReferenceUri = 'foo'"
        }
      },
      "neighbors": [
          {
          "edge": {
            "labelPropertiesPattern": {
                "labelMatcherExpr": "Observability/HAS_ALERT"
            },
            "direction": "TO"
          },
          "graph": {
              "startingNode": {
              "alias": "alert",
              "labelPropertiesPattern": {
                "labelMatcherExpr": "Observability/Alert"
              }
            }
          }
        }
      ]
    }
  }
},
}

צמתים תואמים

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

אפשר להשתמש באופרטורים OR או AND בlabel_matcher_expr, אבל אי אפשר לשלב בין שני סוגי האופרטורים בביטוי התאמה אחד.

דוגמאות:

• התאמה לעומסי עבודה של מרכז האפליקציות: "Base/apphub.googleapis.com/Workload"
• התאמה של עומסי עבודה או שירותים: "Base/DiscoveredWorkload OR Base/DiscoveredService"

מאפייני התאמה

מסננים מאפיינים של צומת באמצעות ביטוי ההתאמה property_matcher_expr.

יש שני סוגים של נכסים:

• מאפייני מערכת מובנים – מאפיינים שחלים על כל הצמתים והקשתות:
  • לצמתים: NodeName (לצמתים)
  • לשוליים: EdgeName (לשוליים)

• תוויות – רשימת התוויות בצומת או בקצה שאפשר להשתמש בהן עם ביטויי סינון של מאפיינים. לדוגמה:

  (CONTAINS_ANY(alias.Labels, "Base/MCPServer") AND alias.Base/agentregistry/urn = "foo") OR (CONTAINS_ANY(alias.Labels, "Base/Agent") AND alias.Base/agent/framework = "bar")
  

• מאפייני סכימה של דומיין – מאפיינים שספציפיים לסוג משאב, כמו Base/location,‏ Observability/errorRate ו-Base/app/state. השיטה GetSchema מחזירה את המאפיינים האלה.

  לדוגמה, כדי לסנן משאב עם התווית n באזור us-central1, משתמשים בביטוי n.Base/location = "us-central1".

רשימת האופרטורים הנתמכים בביטויי התאמה של מאפיינים מופיעה במאמר בנושא LabelPropertiesPattern.

הוראות ניווט בקצה

במקרה של קצוות, edge.direction מציין את הכיוון, וערך ברירת המחדל הוא DIRECTION_UNSPECIFIED. אפשר להגדיר אחד מהערכים הבאים כדי לציין את הקשר בין צומת המקור לצומת היעד.

• ‫TO – מהמקור ליעד.
• ‫FROM – מהיעד אל המקור.
• ‫ANY – הקשר בין הצמתים הוא דו-כיווני.

אם הכיוון ידוע, משתמשים ב-TO או ב-FROM. שאילתות דו-כיווניות "ANY" מרחיבות את מצב המעבר באופן קומבינטורי ומגדילות את זמן האחזור של ה-API.

מגבלות

גודל השאילתה והטופולוגיה:

• יכול להיות שייקח יותר זמן לקבל תוצאות לשאילתות מורכבות יותר. התנאים האלה כוללים:
  • propertyMatcherExpr כולל יותר מ-4 השוואות.
  • המעבר בטופולוגיה כולל יותר מחמש קפיצות בהרצת השאילתה.
• חלוקה לדפים לא אפשרית עבור נתוני טופולוגיה שמוחזרים.
• ה-API מחזיר עד 1,000 נתיבים ייחודיים.
• לנתוני יכולת התבוננות:
  • צמתים מסוג Observability/Alert תומכים רק באופרטור השוויון (=).
  • ב-Observability/SENDS_TRAFFIC edges אין תמיכה במסנני נכסים.

זמינות הנתונים:

• ‫Google Cloud Observability לא תומך בטלמטריה לכל השירותים ועומסי העבודה של מרכז האפליקציות. רשימה של משאבי התשתית הנתמכים זמינה במאמר תשתית נתמכת של ניטור אפליקציות.
• כשמציגים טופולוגיה של אפליקציה ב-מרכז האפליקציות, המשאבים שאפשר לשתף בין אפליקציות לא נכללים בהדמיה.
• כשמוחקים אירוע של תובנות מ-Developer Connect, יכול להיות שהאירוע עדיין יופיע בתוצאות של שאילתות לגבי App Topology למשך כמה ימים.
• לגבי נתוני אבטחה ותאימות שסופקו על ידי Security Command Center:
  • הנתונים שסיפקת נמצאים במצב תצוגה מקדימה
  • הנתונים זמינים רק לפרויקטים ולאפליקציות בארגון Google Cloud.