Monitor GCP Kubernetes Engine (GKE) Metrics

The Google Kubernetes Engine (GKE) integration brings cluster metrics (container CPU and memory utilization, container restarts, pod startup latency, pod and node network throughput, volume usage, and node health) into SigNoz, with a pre-built dashboard for the service.

GKE publishes its system metrics to Cloud Monitoring. SigNoz reads them through the OpenTelemetry Collector running in your GCP project.

This page covers the GKE system metrics that GKE reports to Cloud Monitoring (the kubernetes.io/* metrics). If you want to scrape the cluster directly instead, and collect logs and traces from your workloads, use Kubernetes monitoring with the SigNoz k8s-infra chart or the manual GKE guide. The two approaches are complementary: this one needs nothing installed in the cluster, the other gives finer resolution and covers logs.

Choose a setup method

Available now. You run the OpenTelemetry Collector in your own GCP project and add the GKE metrics to its configuration. You control which metrics are pulled and how often.

Complete the GCP integration setup once, then follow the steps on this page for each project that hosts the clusters you want to monitor.

Prerequisites

Before configuring this service, complete the shared GCP integration setup:

Your GCP account is connected in SigNoz, and the project running your GKE clusters is in Projects to Monitor.
The OpenTelemetry Collector is deployed and running.
The signoz-integration service account has roles/monitoring.viewer on the project that hosts the clusters. See Create a service account.
The Cloud Monitoring API is enabled in that project.
System metrics collection is enabled on the cluster. It is on by default. If it was turned off, re-enable it under the cluster's Observability settings, or the kubernetes.io/* metrics never reach Cloud Monitoring for the Collector to read. See Configure metrics collection.

Step 1: Enable the service in SigNoz

In SigNoz, go to Integrations > Google Cloud Platform.
Select GCP Kubernetes Engine from the service list.
Toggle Metric Collection on to activate the pre-built dashboard.
Open the Data Collected tab and note the metrics listed there. These are the metrics the dashboard's panels query.

Enabling the toggle does not start collection on its own. The metrics that reach SigNoz are exactly the ones in your Collector's metrics_list. If you skip a metric in step 2, its dashboard panel stays empty.

Step 2: Add the metrics to your Collector config

Open the otel-collector-config.yaml you created in Deploy the Collector and add the GKE metric names to the metrics_list of the googlecloudmonitoring receiver for the project your clusters run in. Only the metrics_list shown below changes; leave the rest of the file as is:

receivers:
  googlecloudmonitoring:
    project_id: "<monitored-project-id>"
    collection_interval: 300s   # 5 minutes; minimum is 60s
    metrics_list:
      # Container CPU and memory
      - metric_name: "kubernetes.io/container/cpu/limit_utilization"
      - metric_name: "kubernetes.io/container/cpu/request_utilization"
      - metric_name: "kubernetes.io/container/memory/limit_utilization"
      - metric_name: "kubernetes.io/container/memory/request_utilization"
      # Workload health
      - metric_name: "kubernetes.io/container/restart_count"
      - metric_name: "kubernetes.io/pod/latencies/pod_first_ready"
      # Pod network
      - metric_name: "kubernetes.io/pod/network/received_bytes_count"
      - metric_name: "kubernetes.io/pod/network/sent_bytes_count"
      # Storage
      - metric_name: "kubernetes.io/pod/volume/utilization"
      # Nodes
      - metric_name: "kubernetes.io/node/cpu/allocatable_utilization"
      - metric_name: "kubernetes.io/node/memory/allocatable_utilization"
      - metric_name: "kubernetes.io/node/ephemeral_storage/used_bytes"
      - metric_name: "kubernetes.io/node/ephemeral_storage/allocatable_bytes"
      - metric_name: "kubernetes.io/node/network/received_bytes_count"
      - metric_name: "kubernetes.io/node/network/sent_bytes_count"
      - metric_name: "kubernetes.io/node/status_condition"

Verify these values:

<monitored-project-id>: The GCP project that hosts your GKE clusters. It must be one of the entries in your Projects to Monitor list.

If your clusters span several projects, add one named receiver per project (googlecloudmonitoring/<name>) and list them all in the metrics pipeline. See Configure multiple projects.

The receiver polls every metric in the list once per collection_interval, and the Monitoring API bills per read call, so keep the list to the metrics your dashboards and alerts actually use. This list is longer than most services, so it is the one to trim first if your Monitoring API bill matters. See Cost and tuning.

These metrics carry a series per container, pod, or node, so a large cluster produces many more series than a single database instance does. Start at the default 300s and lower it only if you need the resolution.

Step 3: Apply the configuration

The Collector loads its config from the signoz-collector-config secret, so a config change needs a new secret version and a redeploy:

Save your updated otel-collector-config.yaml.
Add a new secret version (step 2 of Deploy the Collector).
Redeploy the Cloud Run service (step 3).

Validate

Wait one or two collection intervals (up to about 5 minutes with the default 300s).
In SigNoz, go to Dashboards and open the Kubernetes Engine dashboard. Panels should start filling in.
To check a single metric, open Metrics Explorer and query kubernetes.io/container/cpu/limit_utilization.

What's collected

Metrics

See the Data Collected tab in the SigNoz integration for the definitive list the dashboard uses, and the GKE system metrics list for full definitions.

Metric name	Unit	Type
`kubernetes.io/container/cpu/limit_utilization`	Ratio	Gauge
`kubernetes.io/container/cpu/request_utilization`	Ratio	Gauge
`kubernetes.io/container/memory/limit_utilization`	Ratio	Gauge
`kubernetes.io/container/memory/request_utilization`	Ratio	Gauge
`kubernetes.io/container/restart_count`	Count	Sum
`kubernetes.io/pod/latencies/pod_first_ready`	Seconds	Gauge
`kubernetes.io/pod/network/received_bytes_count`	Bytes	Sum
`kubernetes.io/pod/network/sent_bytes_count`	Bytes	Sum
`kubernetes.io/pod/volume/utilization`	Ratio	Gauge
`kubernetes.io/node/cpu/allocatable_utilization`	Ratio	Gauge
`kubernetes.io/node/memory/allocatable_utilization`	Ratio	Gauge
`kubernetes.io/node/ephemeral_storage/used_bytes`	Bytes	Gauge
`kubernetes.io/node/ephemeral_storage/allocatable_bytes`	Bytes	Gauge
`kubernetes.io/node/network/received_bytes_count`	Bytes	Sum
`kubernetes.io/node/network/sent_bytes_count`	Bytes	Sum
`kubernetes.io/node/status_condition`	Bool	Gauge

Dashboard panels

The pre-built dashboard has 15 panels in five sections:

CPU and memory. Container resource pressure, each as a time series: % Container CPU Limit Utilization, % Container CPU Request Utilization, % Container Memory Limit Utilization, and % Container Memory Request Utilization. Usage against limit shows how close a container is to being throttled or OOM killed; usage against request shows how well the request is sized.

Workload health. Two tables: Container Restarts (total), which lists only containers that have restarted, and Pod First-Ready Latency, the time from pod creation to first Ready state.

Network. Pod Network Receive Throughput and Pod Network Sent Throughput, in bytes per second per pod.

Storage. % PVC Volume Utilization, PersistentVolumeClaim usage as a percentage of capacity.

Nodes (namespace agnostic). Six node-level panels: % Node CPU Allocatable Utilization, % Node Memory Allocatable Utilization, Node status conditions (a table filtered to unhealthy states), % Node Ephemeral Storage Utilization, Node Network Receive Throughput, and Node Network Sent Throughput.

Three single-select variables scope the panels: project_id, cluster_name, and namespace_name.

Pre-built dashboards are read-only. To customize one, use Export JSON from the dashboard menu and import it as a new dashboard.

Node metrics have no namespace dimension, so the Nodes (namespace agnostic) section ignores the namespace_name variable. Those six panels always show every node in the selected cluster.

Troubleshooting

A dashboard panel is empty. The metric backing that panel is missing from your metrics_list. Compare the Data Collected tab against your otel-collector-config.yaml, add what's missing, and repeat step 3.

No GKE metrics at all. Confirm the signoz-integration service account holds roles/monitoring.viewer on the project in project_id, and that the Cloud Monitoring API is enabled there. Then confirm system metrics collection is still enabled on the cluster, and check the Cloud Run logs for googlecloudmonitoring receiver errors.

The Container Restarts table is empty. That is the healthy state. The panel excludes containers with no restarts, so an empty table means nothing has restarted in the selected window.

Node panels ignore the namespace filter. Expected. Node metrics are not namespaced, so the filter cannot apply to them.

% PVC Volume Utilization is empty. pod/volume/utilization only reports for pods with a PersistentVolumeClaim. Workloads using only ephemeral storage produce no series here.

Limit utilization panels are empty for some workloads. limit_utilization is only reported for containers that set a CPU or memory limit. Containers with no limit set have nothing to divide by, so they are absent from those panels. The request panels behave the same way for containers with no request.

Next steps

Create alerts on container restart spikes, CPU or memory utilization approaching the limit, node status conditions turning unhealthy, or PVCs nearing capacity.
Build custom dashboards to correlate cluster saturation with traces from the services running on it.
Instrument the workloads themselves so pod-level pressure can be tied to request latency and errors.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.