Envoy Json-To-Metadata Filter

  • This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.json_to_metadata.v3.JsonToMetadata.

  • v3 API reference

This filter is configured with rules that will be matched against requests. Each rule has either a series of selectors and can be triggered either when the json attribute is present or missing.

When a rule is triggered, dynamic metadata will be added based on the configuration of the rule. If present, it’s value is extracted and used along with the specified key as metadata. If missing, on missing case is triggered and the value specified is used for adding metadata.

The metadata can then be used for load balancing decisions, consumed from logs, etc.

A typical use case for this filter is to dynamically match a specified json attribute of requests with rate limit. For this, a given value of the JSON keys would be extracted and attached to the request as dynamic metadata which would then be used to match a rate limit action on metadata.

The Json to metadata filter stops iterating to next filter until we have the whole payload to extract the Json attributes or encounter error.


A sample filter configuration to route traffic to endpoints based on the presence or absence of a version attribute could be:

25          http_filters:
26          - name: envoy.filters.http.json_to_metadata
27            typed_config:
28              "@type": type.googleapis.com/envoy.extensions.filters.http.json_to_metadata.v3.JsonToMetadata
29              request_rules:
30                rules:
31                - selectors:
32                  - key: version
33                  on_present:
34                    metadata_namespace: envoy.lb
35                    key: version
36                  on_missing:
37                    metadata_namespace: envoy.lb
38                    key: default
39                    value: "true"
40                    preserve_existing_metadata_value: true
41                  on_error:
42                    metadata_namespace: envoy.lb
43                    key: default
44                    value: "true"
45                    preserve_existing_metadata_value: true


The json to metadata filter outputs statistics in the http.<stat_prefix>.json_to_metadata. namespace. The stat prefix comes from the owning HTTP connection manager.






Total requests that succeed to parse the json body. Note that a pure string or number body is treated as a successful json body which increases this counter.



Total requests that mismatch the content type



Total requests without content body



Total requests with invalid json body