À propos des requêtes

Ce document décrit les composants d'une requête de topologie d'application et la syntaxe de la requête.

Composants de requête

Les requêtes App Topology se composent de plusieurs éléments :

  • Nœuds : ressources Google Cloud découvertes ou ressources enregistrées dans App Hub ou Agent Registry. Voici quelques exemples de nœuds :

    • Une VM Compute Engine
    • Image de conteneur dans Artifact Registry
    • Un agent
    • Une alerte Cloud Monitoring
    • Une application, un service ou une charge de travail App Hub
    • Une faille

    Les ressources que vous pouvez interroger dépendent du domaine que vous choisissez. Le domaine SRE inclut toutes les ressources compatibles.

  • Propriétés : propriétés d'un nœud que vous pouvez utiliser pour affiner une requête. Par exemple, vous pouvez rechercher une faille avec un ID CVE spécifique.

  • Arête : relation directionnelle entre deux nœuds.

Structure d'une requête

Cette section présente la structure des requêtes. Pour en savoir plus, consultez la documentation de référence de l'outil generate_discovered_resources_topology.

Les requêtes utilisent la syntaxe de filtrage AIP-160.

Voici les principaux éléments d'une requête :

  • Les requêtes commencent par un startingNode qui spécifie un nœud racine.
  • Vous définissez des relations avec la racine startingNode à l'aide de neighbor. L'élément neighbor définit les nœuds et les arêtes connectés.
  • LabelPropertiesPattern spécifie les expressions de correspondance.
    • label_matcher_expr : expression de correspondance pour les libellés de nœuds ou d'arêtes.
    • property_matcher_expr : expression de correspondance permettant de filtrer des propriétés spécifiques d'un nœud ou d'un bord.
  • Vous définissez une relation directionnelle à l'aide du champ direction.

L'exemple suivant montre une requête pour les alertes associées à la charge de travail App Hub foo dans le projet web-project. Il montre également l'utilisation de alias pour étiqueter les nœuds afin qu'ils soient plus faciles à référencer dans les expressions suivantes.

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

Nœuds correspondants

Spécifiez les types de ressources (nœuds) à l'aide de l'expression de correspondance label_matcher_expr. Vous pouvez faire correspondre un ou plusieurs types de nœuds.

Un label_matcher_expr peut utiliser des opérateurs OR ou AND, mais vous ne pouvez pas mélanger les deux types d'opérateurs dans une même expression de correspondance.

Exemples :

  • Faire correspondre les charges de travail App Hub : "Base/apphub.googleapis.com/Workload"
  • Faites correspondre les charges de travail ou les services découverts : "Base/DiscoveredWorkload OR Base/DiscoveredService"

Établissements avec correspondance

Filtrez les attributs d'un nœud à l'aide de l'expression de correspondance property_matcher_expr.

Il existe deux types de propriétés :

  • Propriétés système intégrées : propriétés qui s'appliquent à tous les nœuds et à toutes les arêtes :
    • Pour les nœuds : NodeName (pour les nœuds)
    • Pour les arêtes : EdgeName (pour les arêtes)

  • Libellés : liste des libellés sur un nœud ou un bord qui peuvent être utilisés avec des expressions de filtre de propriété. Exemple :

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

  • Propriétés du schéma de domaine : propriétés spécifiques à un type de ressource, telles que Base/location, Observability/errorRate et Base/app/state. La méthode GetSchema renvoie ces propriétés.

    Par exemple, pour filtrer une ressource avec le libellé n dans la région us-central1, utilisez l'expression n.Base/location = "us-central1".

Pour obtenir la liste des opérateurs compatibles dans les expressions de correspondance de propriétés, consultez LabelPropertiesPattern.

Directions Edge

Pour les arêtes, edge.direction spécifie la direction, et la valeur par défaut est DIRECTION_UNSPECIFIED. Vous pouvez définir l'une des valeurs suivantes pour indiquer la relation entre le nœud source et le nœud de destination.

  • TO : de la source à la destination.
  • FROM : de la destination à la source.
  • ANY : la relation entre les nœuds est bidirectionnelle.

Lorsque le sens est connu, utilisez TO ou FROM. Les requêtes bidirectionnelles "ANY" développent l'état de traversée de manière combinatoire et augmentent la latence de l'API.

Limites

Taille de la requête et de la topologie :

  • Les réponses aux requêtes peuvent prendre plus de temps si elles sont plus complexes. Cela inclut les conditions suivantes :
    • propertyMatcherExpr inclut plus de quatre comparaisons.
    • La traversée de la topologie inclut plus de cinq sauts dans l'exécution de la requête.
  • La pagination n'est pas compatible avec les données de topologie renvoyées.
  • L'API renvoie un maximum de 1 000 chemins uniques.
  • Pour les données d'observabilité :
    • Les nœuds Observability/Alert n'acceptent que l'opérateur d'égalité (=).
    • Les arêtes Observability/SENDS_TRAFFIC ne sont pas compatibles avec les filtres de propriété.

Disponibilité des données :

  • Google Cloud Observability n'est pas compatible avec la télémétrie pour tous les services et charges de travail App Hub. Pour obtenir la liste des ressources d'infrastructure compatibles, consultez Infrastructure compatible avec Application Monitoring.
  • Lorsque vous affichez une topologie pour une application App Hub, les ressources qui peuvent être partagées entre les applications ne sont pas incluses dans la visualisation.
  • Lorsque vous supprimez un événement d'insights Developer Connect, il peut encore apparaître dans les résultats de requête d'App Topology pendant quelques jours.
  • Pour les données de sécurité et de conformité fournies par Security Command Center :
    • Les données fournies sont en version preview.
    • Les données ne sont disponibles que pour les projets et les applications d'une organisation Google Cloud.