GCP Cloud Platform Monitoring overview
- Latest Dynatrace
- Explanation
This page explains the core concepts behind GCP Cloud Platform Monitoring. To start connecting your Google Cloud environment, see Create a GCP connection.
Architecture at a glance
GCP Cloud Platform Monitoring uses three Dynatrace-side assets to authenticate with your Google Cloud environment and read telemetry through three flows: metrics, topology, and logs.
- Dynatrace principal
Single Dynatrace-managed identity hosted within the Dynatrace Google Cloud environment. This is the service account Dynatrace uses to impersonate your service account. Dynatrace creates it automatically with your first GCP connection. It is unique to your Dynatrace environment and can't be reused across environments.
- GCP connection
Dynatrace-side object that links to your monitoring service account. You create the service account in Google Cloud and grant the Dynatrace principal impersonation rights on it. Each connection maps to one service account, and the roles you grant to that service account define which resources Dynatrace can access.
- Pulled by Dynatrace
Metrics and topology. Dynatrace uses service account impersonation, so no credentials are stored.
- Pushed from your Google Cloud environment (both optional)
- The asset feed, which authenticates with a Google-issued OIDC token.
- Log forwarding, which uses a Dynatrace ingest token. You create the log sinks yourself and connect them to the
dt-logsPub/Sub topic.
- Monitoring configuration
Defines which services, metrics, filters, and enrichment rules to apply.
DYNATRACE (SaaS) GOOGLE CLOUD┌──────────────────────────────────────┐ ┌───────────────────────────────────────────┐│ Dynatrace principal │ impersonate │ Monitoring service account ││ (Dynatrace-managed service account) │─────────────▶│ (linked from the GCP connection) ││ │ tokenCreator │ viewer roles: monitoring.viewer, ││ ┌─────────────────────────────────┐ │ │ cloudasset.viewer, browser ││ │ GCP connection │ │ │ ││ │ service account impersonation │ │ │ │ ││ └───────────────┬─────────────────┘ │ │ ▼ ││ │ referenced by │ │ Monitored projects / folders / org ││ ┌───────────────▼─────────────────┐ │ │ ┌────────────┬────────────┬───────────┐ ││ │ Monitoring configuration │ │ │ │ Cloud │ Cloud Asset│ Cloud │ ││ │ feature sets, filters, │ │ │ │ Monitoring │ Inventory │ Logging │ ││ │ enrichment, monitoring scope │ │ │ │ (metrics) │ (topology) │ (logs) │ ││ └─────────────────────────────────┘ │ │ └────────────┴────────────┴───────────┘ │└──────────────────────────────────────┘ └───────────────────────────────────────────┘DATA FLOWSMetrics Cloud Monitoring ───────────────── pull, every 5 minutes ──────────▶ DynatraceTopology Cloud Asset Inventory ───────────── pull, hourly snapshot ──────────▶ DynatraceAsset feed (optional) ─▶ Pub/Sub (dt-asset-feed-<id>) ─ push, OIDC ─▶ /api/gcp/assetfeed/v1/eventsLogs (optional) Cloud Logging ─your sink▶ Pub/Sub (dt-logs-<id>) ─▶ Dataflow ─ token ─▶ /api/gcp/pubsub/v1/logsIngested metrics and logs are linked to their Smartscape entity via dt.smartscape_source.id.
The following sections describe each concept in detail.
How access works
Dynatrace authenticates with service account impersonation—no credentials are stored or managed. You grant the Dynatrace principal impersonation rights on your monitoring service account (roles/iam.serviceAccountTokenCreator).
You choose the monitoring scope by granting IAM roles to that service account at the level that fits your needs—project, folder, or organization.
See the diagram in Architecture at a glance.
Service account project vs monitored projects
GCP Cloud Platform Monitoring involves two different types of GCP project, each with distinct requirements. The service account project hosts the monitoring service account—enable the five required APIs here (four more if you forward logs) and grant the Dynatrace principal impersonation rights here.
Each monitored project needs monitoring.googleapis.com enabled and the service account granted roles/monitoring.viewer, roles/cloudasset.viewer, and roles/browser.
Topology can flow from a folder- or org-level IAM binding without per-project API access, so metrics can be missing while topology appears. See Verify monitoring API on each monitored project.
To check that Dynatrace authenticates against your service account, see Verify the Dynatrace principal has impersonation rights.
Permissions and APIs
Required IAM roles
Grant the following roles to the monitoring service account at the scope you want to monitor — project, folder, or organization. The scope determines which resources Dynatrace can access.
| Role | Purpose |
|---|---|
roles/monitoring.viewer | Fetch time-series data and metric descriptors |
roles/cloudasset.viewer | Fetch resource inventory via Cloud Asset Inventory |
roles/browser | List and get resources within the binding scope |
roles/browser is bound at the configured scope. At project scope it can list projects; at folder scope, folders and projects; at organization scope, the organization and all folders and projects. Folder filtering without granting roles/browser at folder level will not work.
Required APIs
Enable the following APIs on the Google Cloud project where the monitoring service account was created.
| API | Purpose |
|---|---|
cloudresourcemanager.googleapis.com | List projects, folders, and organizations |
cloudasset.googleapis.com | Fetch resource inventory |
monitoring.googleapis.com | Fetch metrics — enabled by default on new GCP projects |
pubsub.googleapis.com | Pub/Sub topics and subscriptions for the asset feed and log forwarding |
iam.googleapis.com | Service account IAM and OIDC token creation |
If your organization restricts default-enabled APIs, manually enable monitoring.googleapis.com on each monitored project:
gcloud services enable monitoring.googleapis.com --project=MONITORED_PROJECT_ID
If you forward logs, also enable the following APIs:
| API | Purpose |
|---|---|
logging.googleapis.com | Cloud Logging and log sinks |
dataflow.googleapis.com | Dataflow job that forwards the logs |
storage.googleapis.com | Cloud Storage buckets for the Dataflow job |
secretmanager.googleapis.com | Secret Manager secret that holds the Log Ingest token |
Google Cloud limits the requests that the project holding the monitoring service account can send to the Cloud Monitoring API. Increase the ListTimeSeries quota there before you monitor large environments. See GCP performance and quotas.
Topology
Dynatrace discovers your Google Cloud resource inventory with Cloud Asset Inventory: an initial scrape when you create the connection, a full scrape every hour, and an optional asset feed for near-real-time changes. Dynatrace stores each resource as a topology entity in Dynatrace (called a Smartscape on Grail entity). For details on entity attributes, relationships, and location field behavior, see GCP topology.
Metrics
Dynatrace polls Google Cloud Monitoring every five minutes and ingests metrics for supported services using a curated recommended set. For services or metrics not on the list, you can ingest any Cloud Monitoring metric directly. Choose whether to collect from all visible projects or only scoping projects. For details, see Cloud Monitoring metrics.
Logs
Dynatrace integrates with Google Cloud Log Router. Log sinks that you create route logs to a Pub/Sub topic. From there, a Dataflow job in your Google Cloud project forwards them to Dynatrace. For details on the forwarding pipeline and configuration, see GCP logs and events.
Telemetry data in context
Dynatrace links ingested metrics and logs to the Smartscape on Grail entity they originate from — for example, a Compute Engine instance or Cloud SQL database. Each linked record carries dt.smartscape_source.id (entity ID) and dt.smartscape_source.type (entity type), enabling correlation of telemetry with topology in DQL and 
Clouds.
Smartscape on Grail entity┌──────────────────────────────────────────────────────────┐│ type: GCP_COMPUTE_GOOGLEAPIS_COM_INSTANCE ││ id: GCP_COMPUTE_GOOGLEAPIS_COM_INSTANCE-A1B2C3D4 ││ gcp.project.id: my-project ││ gcp.location: us-central1-a ││ gcp.resource.name: //compute.googleapis.com/projects/ ││ my-project/zones/us-central1-a/ ││ instances/my-instance ││ gcp.object: { ...full asset config... } │└──────────────────▲───────────────────────────────────────┘│ dt.smartscape_source.id┌────────────┴──────────────┐│ │Metric data point Log record┌─────────────────────────────┐ ┌─────────────────────────────┐│ metric.key: cloud.gcp. │ │ gcp.log.id: GCEGuestAgent ││ gce_instance.compute_ │ │ gcp.resource.type: ││ googleapis_com.instance. │ │ gce_instance ││ cpu.utilization │ │ severity: INFO ││ gcp.project.id: my-project │ │ message: "Completed ││ gcp.location: us-central1-a │ │ adding/removing routes…" ││ value: 0.42 │ │ dt.smartscape_source.id: ││ dt.smartscape_source.id: │ │ GCP_COMPUTE_GOOGLEAPIS_ ││ GCP_COMPUTE_GOOGLEAPIS_ │ │ COM_INSTANCE-A1B2C3D4 ││ COM_INSTANCE-A1B2C3D4 │ │ dt.smartscape_source.type: │└─────────────────────────────┘ │ GCP_COMPUTE_GOOGLEAPIS_ ││ COM_INSTANCE │└─────────────────────────────┘
Tags and labels
You can reuse your existing Google Cloud tags and labels in Dynatrace in two ways:
- Filtering: Use labels and tags to control which resources are monitored. Include or exclude resources based on label key-value pairs or tag IDs. This is configured per connection in Advanced mode.
- Enrichment: Bring tag and label values onto your ingested telemetry data, or use them to set Dynatrace attributes such as
dt.security_context.
Labels
Google Cloud labels are flat key-value pairs set directly on a resource. When label enrichment is configured, label values are available as gcp.labels.<key> attributes on metrics and logs ingested for that resource. Label changes propagate to Dynatrace within minutes.
GCP resource┌──────────────────────────────────────────────┐│ Labels ││ environment: production ││ team: backend │└──────────────────────┬───────────────────────┘│ enriched as gcp.labels.<key>▼Metric or log data point┌──────────────────────────────────────────────┐│ gcp.labels.environment: production ││ gcp.labels.team: backend │└──────────────────────────────────────────────┘
Tags
Google Cloud tags are hierarchical. Tag keys and values are defined at organization or project level and bound to resources at any scope in the hierarchy. The namespace in the attribute key identifies where the tag key is defined: an organization ID or a project ID. Tag changes can take up to one hour to appear in Dynatrace.
GCP tag hierarchy┌──────────────────────────────────────────────┐│ Organization (178056077565) ││ key: cost-center → eng-123 ││ └─ Project (my-project) ││ key: owner → platform-team ││ └─ gce_instance: my-instance ││ (inherits all parent tag bindings) │└──────────────────────┬───────────────────────┘│ enriched as gcp.tags.<namespace>/<key>▼Metric or log data point┌──────────────────────────────────────────────┐│ gcp.tags.178056077565/cost-center: eng-123 ││ gcp.tags.my-project/owner: platform-team │└──────────────────────────────────────────────┘
Enrichment timing considerations
Both enrichment and filtering depend on Dynatrace having up-to-date label and tag data for each resource.
- Enrichment: Telemetry arriving before a resource is discovered — or before its latest labels and tags are available — is ingested without enrichment attributes. Use OpenPipeline rules to set defaults for missing attributes or drop unenriched records.
- Filtering: If a resource's labels or tags are not yet available when telemetry arrives, it may not match your include filters — Dynatrace will not discover it or collect its metrics until the data is available. This can create a brief monitoring gap for new or recently relabeled resources.