Control plane metrics

By default, the kgateway control plane exposes metrics in Prometheus format. You can use these metrics to monitor the health and performance of your gateway environment. For more information about how metrics are implemented, refer to the kgateway project developer docs.

View control plane metrics

The following steps show you how to quickly view the metrics endpoint of the control plane deployment. To integrate the metrics into your observability stack, see the OpenTelemetry guide.

1. Port-forward the control plane deployment on port 9092.

   kubectl -n kgateway-system port-forward deployment/kgateway 9092

2. Open your browser to the metrics endpoint: http://localhost:9092/metrics.

   Example output:

   # HELP kgateway_controller_reconciliations_total Total controller reconciliations
   # TYPE kgateway_controller_reconciliations_total counter
   kgateway_controller_reconciliations_total{controller="gateway",result="success"} 1
   kgateway_controller_reconciliations_total{controller="gatewayclass",result="success"} 2
   kgateway_controller_reconciliations_total{controller="gatewayclass-provisioner",result="success"} 2
   

Control plane metrics reference

Review the following table to understand more about each metric.

Helpful terms:

• Controller: A Kubernetes controller that reconciles resources as part of the kgateway control plane deployment.

• Resource: A Kubernetes object that is managed by a controller of the control plane.

• Snapshot: A complete, point-in-time representation of the current state of resources that the controller builds and serves to a gateway proxy via the Envoy extensible Discovery Service (XDS) API.

• Sync: The metrics refer to two kinds of syncs:

  • Status sync metrics represent the time it takes for you as a user to view the status that is reported on the resource.
  • Snapshot sync metrics roughly represent the time it takes for a resource change to become effective in the gateway proxies.

• Transform: The process of the control plane converting high-level resources or intermediate representations (IR) into lower-level representations into the structure that the XDS API expects for a snapshot.

Name	Type	Labels	Help
kgateway_controller_reconcile_duration_seconds	histogram	controller	Reconcile duration for controller
kgateway_controller_reconciliations_running	gauge	controller	Number of reconciliations currently running
kgateway_controller_reconciliations_total	counter	controller, result	Total number of controller reconciliations
kgateway_resources_managed	gauge	namespace, parent, resource	Current number of resources managed
kgateway_resources_status_sync_duration_seconds	histogram	gateway, namespace, resource	Duration of time for a resource update to receive a status report
kgateway_resources_status_syncs_completed_total	counter	gateway, namespace, resource	Total number of status syncs completed for resources
kgateway_resources_syncs_started_total	counter	gateway, namespace, resource	Total number of syncs started
kgateway_resources_updates_dropped_total	counter		Total number of resources metrics updates dropped. If this metric is ever greater than 0, all resources subsystem metrics should be considered invalid until process restart
kgateway_resources_xds_snapshot_sync_duration_seconds	histogram	gateway, namespace, resource	Duration of time for a resource update to be synced in XDS snapshots
kgateway_resources_xds_snapshot_syncs_total	counter	gateway, namespace, resource	Total number of XDS snapshot syncs for resources
kgateway_routing_domains	gauge	namespace, gateway, port	Number of domains per listener
kgateway_status_syncer_status_sync_duration_seconds	histogram	syncer	Status sync duration
kgateway_status_syncer_status_syncs_total	counter	syncer, result	Total number of status syncs
kgateway_translator_translation_duration_seconds	histogram	translator	Translation duration
kgateway_translator_translations_running	gauge	translator	Current number of translations running
kgateway_translator_translations_total	counter	translator, result	Total number of translations
kgateway_xds_snapshot_resources	gauge	gateway, namespace, resource	Current number of resources in XDS snapshot
kgateway_xds_snapshot_syncs_total	counter	gateway, namespace	Total number of XDS snapshot syncs
kgateway_xds_snapshot_transform_duration_seconds	histogram	gateway, namespace	XDS snapshot transform duration
kgateway_xds_snapshot_transforms_total	counter	gateway, namespace, result	Total number of XDS snapshot transforms