Metrics - Agent HTTP API

The /agent/metrics endpoints return agent telemetry data in JSON or Prometheus format, including certificate-related metrics.

Certificate-related metrics

Consul exposes certificate expiration and renewal metrics through the existing /agent/metrics endpoint. To retrieve the certificate metrics in a format that is ready for scraping, use the Prometheus output format.

Certificate telemetry is enabled by default. The certificate-related metrics are also available through the same Prometheus output as the rest of Consul's agent telemetry.

For more information about enabling and configuring the certificate telemetry settings, refer to Telemetry parameters for Consul agent configuration files. For workflow guidance and alerting examples, refer to Monitor certificate expiration.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

This table shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Query parameters

• format (string: "") - Optional response format. Use prometheus to return Prometheus-formatted metrics.

Sample request

$ curl \
    http://127.0.0.1:8500/v1/agent/metrics?format=prometheus

Sample response

# HELP consul_mesh_active_root_ca_expiry Seconds until the service mesh root certificate expires. Updated every hour
# TYPE consul_mesh_active_root_ca_expiry gauge
consul_mesh_active_root_ca_expiry{datacenter="dc1"} 864000

# HELP consul_mesh_active_signing_ca_expiry Seconds until the service mesh signing certificate expires. Updated every hour
# TYPE consul_mesh_active_signing_ca_expiry gauge
consul_mesh_active_signing_ca_expiry{datacenter="dc1"} 259200

# HELP consul_agent_tls_cert_expiry Seconds until the agent TLS certificate expires. Updated every hour
# TYPE consul_agent_tls_cert_expiry gauge
consul_agent_tls_cert_expiry{datacenter="dc1",partition="default",node="server-1"} 950400

# HELP consul_leaf_certs_cert_expiry consul_leaf_certs_cert_expiry
# TYPE consul_leaf_certs_cert_expiry gauge
consul_leaf_certs_cert_expiry{datacenter="dc1",partition="default",namespace="default",service="web",kind=""} 86340

# HELP consul_leaf_certs_cert_renewal_failure consul_leaf_certs_cert_renewal_failure
# TYPE consul_leaf_certs_cert_renewal_failure gauge
consul_leaf_certs_cert_renewal_failure{datacenter="dc1",partition="default",namespace="default",service="web",kind="",reason="rate_limited"} 1

Certificate-related metrics

The following certificate-related metrics are emitted through /agent/metrics?format=prometheus:

• consul_mesh_active_root_ca_expiry - Seconds until the active service mesh root CA expires.
• consul_mesh_active_signing_ca_expiry - Seconds until the active service mesh signing CA expires.
• consul_agent_tls_cert_expiry - Seconds until the local agent TLS certificate expires.
• consul_leaf_certs_cert_expiry - Seconds until a cached service leaf certificate expires.
• consul_leaf_certs_cert_renewal_failure - Gauge that indicates whether leaf certificate renewal is currently failing.
• consul_leaf_certs_renewal_success - Counter incremented when leaf certificate renewal succeeds.
• consul_leaf_certs_renewal_failed - Counter incremented when leaf certificate renewal fails for non-rate-limit reasons.
• consul_leaf_certs_renewal_failed_rate_limited - Counter incremented when leaf certificate renewal is rate limited.
• consul_leaf_certs_consecutive_rate_limit_errors - Gauge tracking consecutive leaf renewal rate-limit failures.

Related APIs

For exact certificate expiry timestamps on the service mesh CA roots, refer to the CA roots APIs:

• /connect/ca/roots
• /agent/connect/ca/roots

Those responses include the NotAfter value for the returned CA roots.