Monitoring & Metrics

cilium-agent can be configured to serve Prometheus metrics. Prometheus is a pluggable metrics collection and storage system and can act as a data source for Grafana, a metrics visualization frontend. Unlike some metrics collectors like statsd, Prometheus requires the collectors to pull metrics from each source.

To expose any metrics, invoke cilium-agent with the --prometheus-serve-addr option. This option takes a IP:Port pair but passing an empty IP (e.g. :9090) will bind the server to all available interfaces (there is usually only one in a container).

Exported Metrics

All metrics are exported under the cilium Prometheus namespace. When running and collecting in Kubernetes they will be tagged with a pod name and namespace.


  • endpoint_count: Number of endpoints managed by this agent
  • endpoint_regenerating: Number of endpoints currently regenerating
  • endpoint_regenerations: Count of all endpoint regenerations that have completed, tagged by outcome

Policy Imports

  • policy_count: Number of policies currently loaded
  • policy_max_revision: Highest policy revision number in the agent
  • policy_import_errors: Number of times a policy import has failed

Policy L7 (HTTP/Kafka)

  • policy_l7_parse_errors_total: Number of total L7 parse errors
  • policy_l7_forwarded_total: Number of total L7 forwarded requests/responses
  • policy_l7_denied_total: Number of total L7 denied requests/responses due to policy
  • policy_l7_received_total: Number of total L7 received requests/responses

Events external to Cilium

  • event_ts: Last timestamp when we received an event. Further labeled by source: api, containerd, k8s.

Cilium as a Kubernetes pod

The Cilium Prometheus reference configuration configures jobs that automatically collect pod metrics marked with the appropriate two labels.

Your Cilium spec will need these annotations: "true" "9090"

The reference Cilium Kubernetes DaemonSet Kubernetes spec is an example of how to configure cilium-agent and set the appropriate labels.

Note: the port can be configured per-pod to any value and the label set accordingly. Prometheus uses this label to discover the port.

To configure automatic metric discovery and collection, Prometheus itself requires a kubernetes_sd_config configuration. The configured rules are used to filter pods and nodes by label and annotation, and tag the resulting metrics series. In the Kubernetes case Prometheus will contact the Kubernetes API server for these lists and must have permissions to do so.

An example promethues configuration can be found alongside the reference Cilium Kubernetes DaemonSet spec.

The critical discovery section is:

- job_name: 'kubernetes-pods'
    - role: pod
    - source_labels: [__meta_kubernetes_pod_label_k8s_app]
      action: keep
      regex: cilium
    - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
      action: keep
      regex: true
    - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
      action: replace
      regex: (.+):(?:\d+);(\d+)
      replacement: ${1}:${2}
      target_label: __address__
    - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
      action: replace
      target_label: __metrics_path__
      regex: (.+)
    - action: labelmap
      regex: __meta_kubernetes_pod_label_(.+)
    - source_labels: [__meta_kubernetes_namespace]
      action: replace
      target_label: kubernetes_namespace
    - source_labels: [__meta_kubernetes_pod_name]
      action: replace
      target_label: kubernetes_pod_name

This job configures prometheus to do a number of things for all pods returned by the Kubernetes API server:

  • find and keep all pods that have labels k8s-app=cilium and
  • extract the IP and port of the pod from address and
  • discover the metrics URL path from the label or use the default of /metrics when it isn’t present
  • populate metrics tags for the Kubernetes namespace and pod name derived from the pod labels

Cilium as a host-agent on a node

Prometheus can use a number of more common service discovery schemes, such as consul and DNS, or a cloud provider API, such as AWS, GCE or Azure. Prometheus documentation contains more information.

It is also possible to hard-code static-config sections that simply contain a hardcoded IP address and port:

- job_name: 'cilium-agent-nodes'
  metrics_path: /metrics
    - targets: ['']
        node-id: i-0598c7d7d356eba47
        node-az: a