View application topology

This document describes how to view the topology map that Application Monitoring creates for your App Hub applications, services, and workloads. The application topology map provides a dynamic view of your application's relationships to help you monitor alerts and traffic, and troubleshoot issues.

Understand the topology map

The application topology map provides a dynamic and actionable view of your application's performance, simplifying monitoring and troubleshooting. The topology map represents your application using nodes and edges, as follows:

• Nodesrepresent your application's services and workloads:

  

• Edgesrepresent your application's traffic between your services and workloads:

  

The topology map is fully interactive. You can zoom in and out, and move nodes around to help you visualize the relationship between your services and workloads. To open a panel that provides additional details about the status of a specific node or edge, click the node or edge.

Before you begin

To generate the application topology map, your trace data must contain application-specific labels. These labels are available only when you instrument your app with OpenTelemetry, send your trace data to the Telemetry API, and register your application with App Hub.

To get started, do the following:

1. Configure Application Monitoring as described in Set up Application Monitoring . Setup for Application Monitoring includes configuring the default trace scope to list all projects that store your trace data .
2. If you are using an App-enabled folder , then your project will have a default Service Usage Restriction policy that prevents you from using the App Topology API. To resolve this, someone with the Organization Policy Administrator role must add apptopology.googleapis.com to the policy allowlist for the app-enabled folder management project. Note that there may also be a policy in place at the organization level. For more information, see Restricting resource usage .

3. Enable the Observability, App Topology, and Telemetry APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role ( roles/serviceusage.serviceUsageAdmin ), which contains the serviceusage.services.enable permission. Learn how to grant roles .

   Enable the APIs

   If you've added other projects to your trace scope, then we recommend you also enable the Observability API for those projects. The application topology map only shows trace edges from trace scope projects that are in the same organization as your App Hub project.

4. To get the permissions that you need to view application topology, ask your administrator to grant you the App Topology viewer ( roles/apptopology.viewer ) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations .

   This predefined role contains the permissions required to view application topology. To see the exact permissions that are required, expand the Required permissionssection:

   Required permissions

   The following permissions are required to view application topology:

   • To generate topology: apptopology.applicationTopologies.generate

   You might also be able to get these permissions with custom roles or other predefined roles .

5. Instrument your application to use OpenTelemetry and to send your trace data to the OTLP endpoint .

View the topology map

1. In the Google Cloud console, go to the Application monitoring page:

   Go to Application monitoring

   If you use the search bar to find this page, then select the result whose subheading is Monitoring .

2. In the project picker of the Google Cloud console, select your App Hub host project or management project.

3. Select an application from the list.

4. Click the Topologytab. The topology map for your application appears.

The topology map is fully interactive. You can zoom in and out, and move nodes around to help you visualize the relationship between your services and workloads. You can also view details about a node or edge:

• To view open alerts or attributes for a service or workload, select the node.
• To view latency and error rate between two nodes, select the edge.

Troubleshoot

For information that might help you understand why the application topology map doesn't display data, see Troubleshoot Application Monitoring .