Sobre as consultas

Este documento descreve os componentes de uma consulta de App Topology e a sintaxe da consulta.

Componentes de consulta

As consultas da App Topology consistem em vários componentes:

  • Nós: recursos descobertos Google Cloud ou registrados no App Hub ou no Agent Registry. Exemplos de nós:

    • Uma VM do Compute Engine
    • Uma imagem do contêiner no Artifact Registry
    • Um agente
    • Um alerta do Cloud Monitoring
    • Um aplicativo, serviço ou carga de trabalho do App Hub
    • Uma vulnerabilidade

    Os recursos que podem ser consultados dependem do domínio escolhido. O domínio SRE inclui todos os recursos compatíveis.

  • Propriedades: atributos de um nó que podem ser usados para refinar uma consulta. Por exemplo, você pode consultar uma vulnerabilidade com um ID de CVE específico.

  • Aresta: uma relação direcional entre dois nós.

Estrutura da consulta

Esta seção oferece uma visão geral da estrutura da consulta. Para mais detalhes, consulte a documentação de referência da ferramenta generate_discovered_resources_topology.

As consultas usam a sintaxe de filtragem AIP-160.

Estes são os principais elementos de uma consulta:

  • As consultas começam com um startingNode que especifica um nó raiz.
  • Você define relações com o startingNode raiz usando neighbor. O elemento neighbor define nós e arestas conectados.
  • LabelPropertiesPattern especifica expressões de correspondência.
    • label_matcher_expr: uma expressão de correspondência para rótulos de nós ou arestas.
    • property_matcher_expr: uma expressão de correspondência para filtrar propriedades específicas de um nó ou uma aresta.
  • Você define uma relação direcional usando o campo direction.

O exemplo a seguir mostra uma consulta de alertas associados à carga de trabalho do App Hub foo no projeto web-project. Ele também mostra o uso de alias para rotular nós e facilitar a referência em expressões subsequentes.

{
"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ós correspondentes

Especifique os tipos de recursos (nós) usando a expressão de correspondência label_matcher_expr. É possível corresponder a um ou vários tipos de nós.

Uma label_matcher_expr pode usar operadores OR ou AND, mas não é possível misturar os dois tipos em uma única expressão de correspondência.

Exemplos:

  • Cargas de trabalho do App Hub correspondentes: "Base/apphub.googleapis.com/Workload"
  • Corresponder cargas de trabalho ou serviços descobertos: "Base/DiscoveredWorkload OR Base/DiscoveredService"

Propriedades correspondentes

Filtre atributos de um nó usando a expressão de correspondência property_matcher_expr.

Há dois tipos de propriedades:

  • Propriedades do sistema integradas: propriedades que se aplicam a todos os nós e arestas:
    • Para nós: NodeName (para nós)
    • Para bordas: EdgeName (para bordas)

  • Marcadores: a lista de marcadores em um nó ou uma aresta que pode ser usada com expressões de filtro de propriedade. Exemplo:

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

  • Propriedades do esquema de domínio: propriedades específicas de um tipo de recurso, como Base/location, Observability/errorRate e Base/app/state. O método GetSchema retorna essas propriedades.

    Por exemplo, para filtrar um recurso com o rótulo n na região us-central1, use a expressão n.Base/location = "us-central1".

Para uma lista de operadores compatíveis em expressões de correspondência de propriedades, consulte LabelPropertiesPattern.

Botões de direções

Para arestas, edge.direction especifica a direção, e o padrão é DIRECTION_UNSPECIFIED. É possível definir um dos seguintes valores para indicar a relação entre o nó de origem e o nó de destino.

  • TO: da origem ao destino.
  • FROM: do destino para a origem.
  • ANY: a relação entre os nós é bidirecional.

Quando a direção for conhecida, use TO ou FROM. As consultas bidirecionais "ANY" expandem o estado de travessia de forma combinatória e aumentam a latência da API.

Limitações

Tamanho da consulta e da topologia:

  • As respostas a consultas podem levar mais tempo para retornar resultados se forem mais complexas. Isso inclui as seguintes condições:
    • propertyMatcherExpr inclui mais de quatro comparações.
    • O percurso da topologia inclui mais de cinco hops na execução da consulta.
  • A paginação não é compatível com os dados de topologia retornados.
  • A API retorna no máximo 1.000 caminhos exclusivos.
  • Para dados de observabilidade:
    • Os nós Observability/Alert só são compatíveis com o operador de igualdade (=).
    • As arestas Observability/SENDS_TRAFFIC não são compatíveis com filtros de propriedade.

Disponibilidade de dados:

  • A Observabilidade do Google Cloud não oferece suporte à telemetria para todos os serviços e cargas de trabalho do App Hub. Para uma lista de recursos de infraestrutura compatíveis, consulte Infraestrutura compatível com o Application Monitoring.
  • Ao visualizar uma topologia de um aplicativo do App Hub, os recursos que podem ser compartilhados entre aplicativos não são incluídos na visualização.
  • Quando você exclui um evento de insights do Developer Connect, ele ainda pode aparecer nos resultados da consulta de App Topology por alguns dias.
  • Para dados de segurança e compliance fornecidos pelo Security Command Center:
    • Os dados fornecidos estão em pré-lançamento.
    • Os dados estão disponíveis apenas para projetos e aplicativos em uma organização do Google Cloud.