gRPC statistics

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

This extension may be referenced by the qualified name envoy.filters.http.grpc_stats

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

gRPC statistics filter configuration overview.

extensions.filters.http.grpc_stats.v3.FilterConfig

[extensions.filters.http.grpc_stats.v3.FilterConfig proto]

gRPC statistics filter configuration

{
  "emit_filter_state": "...",
  "individual_method_stats_allowlist": "{...}",
  "stats_for_all_methods": "{...}",
  "enable_upstream_stats": "..."
}
emit_filter_state

(bool) If true, the filter maintains a filter state object with the request and response message counts.

individual_method_stats_allowlist

(config.core.v3.GrpcMethodList) If set, specifies an allowlist of service/methods that will have individual stats emitted for them. Any call that does not match the allowlist will be counted in a stat with no method specifier: cluster.<name>.grpc.*.

Only one of individual_method_stats_allowlist, stats_for_all_methods may be set.

stats_for_all_methods

(BoolValue) If set to true, emit stats for all service/method names.

If set to false, emit stats for all service/message types to the same stats without including the service/method in the name, with prefix cluster.<name>.grpc. This can be useful if service/method granularity is not needed, or if each cluster only receives a single method.

Attention

This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.

Attention

If neither individual_method_stats_allowlist nor stats_for_all_methods is set, the behavior will default to stats_for_all_methods=false. This default value is changed due to the previous value being deprecated. This behavior can be changed with runtime override envoy.deprecated_features.grpc_stats_filter_enable_stats_for_all_methods_by_default.

Only one of individual_method_stats_allowlist, stats_for_all_methods may be set.

enable_upstream_stats

(bool) If true, the filter will gather a histogram for the request time of the upstream. It works with stats_for_all_methods and individual_method_stats_allowlist the same way request_message_count and response_message_count works.

extensions.filters.http.grpc_stats.v3.FilterObject

[extensions.filters.http.grpc_stats.v3.FilterObject proto]

gRPC statistics filter state object in protobuf form.

{
  "request_message_count": "...",
  "response_message_count": "..."
}
request_message_count

(uint64) Count of request messages in the request stream.

response_message_count

(uint64) Count of response messages in the response stream.