Metadata configurations

Envoy utilizes metadata to transport arbitrary untyped or typed data from the control plane to Envoy. Metadata configurations can be applied to Listeners, clusters, routes, virtual hosts, endpoints, and other elements.

Unlike other configurations, Envoy does not explicitly define the purpose of metadata configurations, which can be used for stats, logging, or filter/extension behavior. Users can define the purpose of metadata configurations for their specific use cases. Metadata configurations offer a flexible way to transport user-defined data from the control plane to Envoy without modifying Envoy’s core API or implementation.

For instance, users can add extra attributes to routes, such as the route owner or upstream service maintainer, to metadata. They can then enable Envoy to log these attributes to the access log or report them to StatsD, among other possibilities. Moreover, users can write a filter/extension to read these attributes and execute any specific logic.

Well-Known Metadata

The following typed_filter_metadata or filter_metadata keys are recognized by Envoy and control built-in behavior. Each entry specifies where the metadata can be configured.

envoy.stats_matcher

Type: envoy.config.metrics.v3.StatsMatcher

Applicable to: Upstream cluster (Cluster.metadata)

Fields: typed_filter_metadata

When present in a cluster’s typed_filter_metadata, Envoy uses the provided StatsMatcher as the stats matcher for that cluster’s stats scope. This per-cluster matcher replaces (not supplements) the global stats matcher configured in the bootstrap StatsConfig. Child scopes created under the cluster scope inherit the matcher unless overridden.

This allows fine-grained control over which stats are created per cluster — for example, enabling a minimal set of stats on high-cardinality clusters to reduce memory and CPU overhead.

Example:

clusters:
- name: my_cluster
  connect_timeout: 0.25s
  type: STATIC
  lb_policy: ROUND_ROBIN
  metadata:
    typed_filter_metadata:
      envoy.stats_matcher:
        "@type": type.googleapis.com/envoy.config.metrics.v3.StatsMatcher
        inclusion_list:
          patterns:
          - prefix: "cluster.my_cluster.upstream_cx"
  load_assignment:
    cluster_name: my_cluster
    endpoints:
    - lb_endpoints:
      - endpoint:
          address:
            socket_address:
              address: 127.0.0.1
              port_value: 10001

In this example, only stats whose names start with cluster.my_cluster.upstream_cx are created for my_cluster, all other cluster stats are suppressed.