Informazioni sulle query

Questo documento descrive i componenti di una query di App Topology e la sintassi della query.

Componenti della query

Le query di App Topology sono costituite da diversi componenti:

  • Nodi: risorse rilevate Google Cloud o registrate in App Hub o Agent Registry. Esempi di nodi includono

    • Una VM di Compute Engine
    • Un'immagine container in Artifact Registry
    • Un agente
    • Un avviso di Cloud Monitoring
    • Un'applicazione, un servizio o un workload App Hub
    • Una vulnerabilità

    Le risorse che puoi interrogare dipendono dal dominio che scegli. Il dominio SRE include tutte le risorse supportate.

  • Proprietà: proprietà di un nodo che puoi utilizzare per perfezionare una query. Ad esempio, puoi eseguire una query per una vulnerabilità con un ID CVE specifico.

  • Arco: una relazione direzionale tra due nodi.

Struttura della query

Questa sezione fornisce una panoramica della struttura della query. Per saperne di più, consulta la documentazione di riferimento per lo strumento generate_discovered_resources_topology.

Le query utilizzano la sintassi di filtro AIP-160.

Gli elementi chiave di una query includono quanto segue:

  • Le query iniziano con un startingNode che specifica un nodo radice.
  • Definisci le relazioni con la radice startingNode utilizzando neighbor. L'elemento neighbor definisce nodi e archi connessi.
  • LabelPropertiesPattern specifica le espressioni di corrispondenza.
    • label_matcher_expr: un'espressione di corrispondenza per le etichette di nodi o archi.
    • property_matcher_expr: un'espressione di corrispondenza per filtrare proprietà specifiche di un nodo o un arco.
  • Definisci una relazione direzionale utilizzando il campo direction.

L'esempio seguente mostra una query per gli avvisi associati al workload App Hub foo nel progetto web-project. Mostra anche l'utilizzo di alias per etichettare i nodi in modo che sia più facile farvi riferimento nelle espressioni successive.

{
"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"
              }
            }
          }
        }
      ]
    }
  }
},
}

Nodi corrispondenti

Specifica i tipi di risorse (nodi) utilizzando l'espressione di corrispondenza label_matcher_expr. Puoi abbinare un singolo tipo di nodo o più tipi.

Un label_matcher_expr può utilizzare gli operatori OR o AND, ma non puoi combinare entrambi i tipi di operatori in una singola espressione di corrispondenza.

Esempi:

  • Corrispondenza dei workload App Hub: "Base/apphub.googleapis.com/Workload"
  • Workload o servizi corrispondenti rilevati: "Base/DiscoveredWorkload OR Base/DiscoveredService"

Proprietà della corrispondenza

Filtra gli attributi di un nodo utilizzando l'espressione di corrispondenza property_matcher_expr.

Esistono due tipi di proprietà:

  • Proprietà di sistema integrate: proprietà che si applicano a tutti i nodi e a tutti gli archi:
    • Per i nodi: NodeName (per i nodi)
    • Per i bordi: EdgeName (per i bordi)

  • Etichette: l'elenco delle etichette su un nodo o un arco che possono essere utilizzate con le espressioni di filtro delle proprietà. Ad esempio:

    (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")

  • Proprietà dello schema di dominio: proprietà specifiche di un tipo di risorsa, ad esempio Base/location, Observability/errorRate e Base/app/state. Il metodo GetSchema restituisce queste proprietà.

    Ad esempio, per filtrare una risorsa con l'etichetta n nella regione us-central1, utilizza l'espressione n.Base/location = "us-central1".

Per un elenco degli operatori supportati nelle espressioni di corrispondenza delle proprietà, consulta LabelPropertiesPattern.

Indicazioni per i bordi

Per i bordi, edge.direction specifica la direzione e il valore predefinito è DIRECTION_UNSPECIFIED. Puoi impostare uno dei seguenti valori per indicare la relazione tra il nodo di origine e il nodo di destinazione.

  • TO - Dall'origine alla destinazione.
  • FROM: dalla destinazione all'origine.
  • ANY: la relazione tra i nodi è bidirezionale.

Quando la direzione è nota, utilizza TO o FROM. Le query bidirezionali "ANY" espandono il combinatore di stati di attraversamento e aumentano la latenza dell'API.

Limitazioni

Dimensioni di query e topologia:

  • Le risposte alle query possono richiedere più tempo per restituire i risultati se sono più complesse. Sono incluse le seguenti condizioni:
    • propertyMatcherExpr include più di 4 confronti.
    • L'attraversamento della topologia include più di cinque hop nell'esecuzione della query.
  • La paginazione non è supportata per i dati di topologia restituiti.
  • L'API restituisce un massimo di 1000 percorsi unici.
  • Per i dati di osservabilità:
    • I nodi Observability/Alert supportano solo l'operatore di uguaglianza (=).
    • I bordi Observability/SENDS_TRAFFIC non supportano i filtri delle proprietà.

Disponibilità dei dati:

  • Google Cloud Observability non supporta la telemetria per tutti i servizi e i carichi di lavoro di App Hub. Per un elenco delle risorse dell'infrastruttura supportate, consulta Infrastruttura supportata per il monitoraggio delle applicazioni.
  • Quando visualizzi una topologia per un'applicazione App Hub, le risorse che possono essere condivise tra le applicazioni non sono incluse nella visualizzazione.
  • Quando elimini un evento di approfondimento di Developer Connect, l'evento potrebbe essere ancora visualizzato nei risultati della query App Topology per alcuni giorni.
  • Per i dati di sicurezza e conformità forniti da Security Command Center:
    • I dati forniti sono in anteprima
    • I dati sono disponibili solo per progetti e applicazioni in un'organizzazione Google Cloud.