About queries

This document describes components of an App Topology query and the query syntax.

Query components

App Topology queries consist of several components:

  • Nodes - Discovered Google Cloud resources or resources registered in App Hub or Agent Registry. Examples of nodes include

    • A Compute Engine VM
    • A container image in Artifact Registry
    • An agent
    • A Cloud Monitoring alert
    • An App Hub application, service, or workload
    • A vulnerability

    The resources that you can query depend on the domain that you choose. The SRE domain includes all supported resources.

  • Properties: Properties of a node that you can use to refine a query. For example, you can query for a vulnerability with a specific CVE ID.

  • Edge: A directional relationship between two nodes.

Query structure

This section provides an overview of the query structure. For more details, see the reference documentation for the generate_discovered_resources_topology tool.

Queries use the AIP-160 filtering syntax.

Key elements of a query include the following:

  • Queries begin with a startingNode that specifies a root node.
  • You define relationships with the root startingNode using neighbor. The neighbor element defines connected nodes and edges.
  • LabelPropertiesPattern specifies match expressions.
    • label_matcher_expr - A match expression for node or edge labels.
    • property_matcher_expr - A match expression to filter for specific properties of a node or edge.
  • You define a directional relationship using the direction field.

The following example shows a query for alerts associated with the App Hub workload foo in the project web-project. It also shows the use of alias to label nodes so that they are easier to reference in subsequent expressions.

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

Matching nodes

Specify resource types (nodes) using the label_matcher_expr match expression. You can match a single node type or multiple types.

A label_matcher_expr can use either OR or AND operators, but you can't mix both types of operators in a single match expression.

Examples:

  • Match App Hub workloads: "Base/apphub.googleapis.com/Workload"
  • Match discovered workloads or services: "Base/DiscoveredWorkload OR Base/DiscoveredService"

Match properties

Filter attributes of a node using the property_matcher_expr match expression.

There are two types of properties:

  • Built-in system properties - Properties that apply to all nodes and edges:
    • For nodes: NodeName (for nodes)
    • For edges: EdgeName (for edges)

  • Labels - The list of labels on a node or edge that can be used with property filter expressions. For example:

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

  • Domain schema properties - Properties specific to a resource type, such as Base/location, Observability/errorRate, and Base/app/state. The GetSchema method returns these properties.

    For example, to filter for a resource with the label n in the region us-central1, use the expression n.Base/location = "us-central1".

For a list of supported operators in property match expressions, see LabelPropertiesPattern.

Edge directions

For edges, edge.direction specifies the direction, and the default is DIRECTION_UNSPECIFIED. You can set one of the following values indicate the relationship between the source node and destination node.

  • TO - From source to destination.
  • FROM - From destination to source.
  • ANY - The relationship between nodes is bidirectional.

When the direction is known, use TO or FROM. Bidirectional queries "ANY" expand traversal state combinatorially and increase API latency.

Limitations

Query and topology size:

  • Query responses can take longer to return results if they are more complex. This includes the following conditions:
    • propertyMatcherExpr includes more than 4 comparisons.
    • Topology traversal includes more than five hops in query execution.
  • Pagination is not supported for returned topology data.
  • The API returns a maximum of 1,000 unique paths.
  • For observability data:
    • Observability/Alert nodes only support the equality (=) operator.
    • Observability/SENDS_TRAFFIC edges don't support property filters.

Data availability:

  • Google Cloud Observability doesn't support telemetry for all App Hub services and workloads. For a list of supported infrastructure resources, see Application Monitoring supported infrastructure.
  • When viewing a topology for an App Hub application, resources that can be shared across applications aren't included in the visualization.
  • When you delete a Developer Connect insights event, the event might still appear in App Topology query results for a few days.
  • For security and compliance data provided by Security Command Center:
    • The provided data is in Preview
    • Data is only available for projects and applications in a Google Cloud organization.