Common access log types

Envoy access logs describe incoming interaction with Envoy over a fixed period of time, and typically cover a single request/response exchange, (e.g. HTTP), stream (e.g. over HTTP/gRPC), or proxied connection (e.g. TCP). Access logs contain fields defined in protocol-specific protobuf messages.

Except where explicitly declared otherwise, all fields describe downstream interaction between Envoy and a connected client. Fields describing upstream interaction will explicitly include upstream in their name.

config.filter.accesslog.v2.AccessLog

[config.filter.accesslog.v2.AccessLog proto]

  1. {
  2.   "name": "...",
  3.   "filter": "{...}",
  4.   "config": "{...}"
  5. }

name

(string) The name of the access log implementation to instantiate. The name must match a statically registered access log. Current built-in loggers include: 1) “envoy.file_access_log”

filter

(config.filter.accesslog.v2.AccessLogFilter) Filter which is used to determine if the access log needs to be written.

config

(Struct) Custom configuration that depends on the access log being instantiated. built-in configurations include: 1) “envoy.file_access_log”: FileAccessLog

config.filter.accesslog.v2.AccessLogFilter

[config.filter.accesslog.v2.AccessLogFilter proto]

  1. {
  2.   "status_code_filter": "{...}",
  3.   "duration_filter": "{...}",
  4.   "not_health_check_filter": "{...}",
  5.   "traceable_filter": "{...}",
  6.   "runtime_filter": "{...}",
  7.   "and_filter": "{...}",
  8.   "or_filter": "{...}"
  9. }

status_code_filter

(config.filter.accesslog.v2.StatusCodeFilter) Status code filter.

Precisely one of status_code_filter, duration_filter, not_health_check_filter, traceable_filter, runtime_filter, and_filter, or_filter must be set.

duration_filter

(config.filter.accesslog.v2.DurationFilter) Duration filter.

Precisely one of status_code_filter, duration_filter, not_health_check_filter, traceable_filter, runtime_filter, and_filter, or_filter must be set.

not_health_check_filter

(config.filter.accesslog.v2.NotHealthCheckFilter) Not health check filter.

Precisely one of status_code_filter, duration_filter, not_health_check_filter, traceable_filter, runtime_filter, and_filter, or_filter must be set.

traceable_filter

(config.filter.accesslog.v2.TraceableFilter) Traceable filter.

Precisely one of status_code_filter, duration_filter, not_health_check_filter, traceable_filter, runtime_filter, and_filter, or_filter must be set.

runtime_filter

(config.filter.accesslog.v2.RuntimeFilter) Runtime filter.

Precisely one of status_code_filter, duration_filter, not_health_check_filter, traceable_filter, runtime_filter, and_filter, or_filter must be set.

and_filter

(config.filter.accesslog.v2.AndFilter) And filter.

Precisely one of status_code_filter, duration_filter, not_health_check_filter, traceable_filter, runtime_filter, and_filter, or_filter must be set.

or_filter

(config.filter.accesslog.v2.OrFilter) Or filter.

Precisely one of status_code_filter, duration_filter, not_health_check_filter, traceable_filter, runtime_filter, and_filter, or_filter must be set.

config.filter.accesslog.v2.ComparisonFilter

[config.filter.accesslog.v2.ComparisonFilter proto]

Filter on an integer comparison.

  1. {
  2.   "op": "...",
  3.   "value": "{...}"
  4. }

op

(config.filter.accesslog.v2.ComparisonFilter.Op) Comparison operator.

value

(core.RuntimeUInt32) Value to compare against.

Enum config.filter.accesslog.v2.ComparisonFilter.Op

[config.filter.accesslog.v2.ComparisonFilter.Op proto]

EQ

(DEFAULT) ⁣=

GE

⁣>=

LE

⁣<=

config.filter.accesslog.v2.StatusCodeFilter

[config.filter.accesslog.v2.StatusCodeFilter proto]

Filters on HTTP response/status code.

  1. {
  2.   "comparison": "{...}"
  3. }

comparison

(config.filter.accesslog.v2.ComparisonFilter, REQUIRED) Comparison.

config.filter.accesslog.v2.DurationFilter

[config.filter.accesslog.v2.DurationFilter proto]

Filters on total request duration in milliseconds.

  1. {
  2.   "comparison": "{...}"
  3. }

comparison

(config.filter.accesslog.v2.ComparisonFilter, REQUIRED) Comparison.

config.filter.accesslog.v2.NotHealthCheckFilter

[config.filter.accesslog.v2.NotHealthCheckFilter proto]

Filters for requests that are not health check requests. A health check request is marked by the health check filter.

  1. {}

config.filter.accesslog.v2.TraceableFilter

[config.filter.accesslog.v2.TraceableFilter proto]

Filters for requests that are traceable. See the tracing overview for more information on how a request becomes traceable.

  1. {}

config.filter.accesslog.v2.RuntimeFilter

[config.filter.accesslog.v2.RuntimeFilter proto]

Filters for random sampling of requests.

  1. {
  2.   "runtime_key": "...",
  3.   "percent_sampled": "{...}",
  4.   "use_independent_randomness": "..."
  5. }

runtime_key

(string, REQUIRED) Runtime key to get an optional overridden numerator for use in the percent_sampled field. If found in runtime, this value will replace the default numerator.

percent_sampled

(type.FractionalPercent) The default sampling percentage. If not specified, defaults to 0% with denominator of 100.

use_independent_randomness

(bool) By default, sampling pivots on the header x-request-id being present. If x-request-id is present, the filter will consistently sample across multiple hosts based on the runtime key value and the value extracted from x-request-id. If it is missing, or use_independent_randomness is set to true, the filter will randomly sample based on the runtime key value alone. use_independent_randomness can be used for logging kill switches within complex nested AndFilter and OrFilter blocks that are easier to reason about from a probability perspective (i.e., setting to true will cause the filter to behave like an independent random variable when composed within logical operator filters).

config.filter.accesslog.v2.AndFilter

[config.filter.accesslog.v2.AndFilter proto]

Performs a logical “and” operation on the result of each filter in filters. Filters are evaluated sequentially and if one of them returns false, the filter returns false immediately.

  1. {
  2.   "filters": []
  3. }

filters

(config.filter.accesslog.v2.AccessLogFilter, REQUIRED)

config.filter.accesslog.v2.OrFilter

[config.filter.accesslog.v2.OrFilter proto]

Performs a logical “or” operation on the result of each individual filter. Filters are evaluated sequentially and if one of them returns true, the filter returns true immediately.

  1. {
  2.   "filters": []
  3. }

filters

(config.filter.accesslog.v2.AccessLogFilter, REQUIRED)

config.filter.accesslog.v2.FileAccessLog

[config.filter.accesslog.v2.FileAccessLog proto]

Custom configuration for an AccessLog that writes log entries directly to a file. Configures the built-in envoy.file_access_log AccessLog.

  1. {
  2.   "path": "...",
  3.   "format": "..."
  4. }

path

(string, REQUIRED) A path to a local file to which to write the access log entries.

format

(string) Access log format. Envoy supports custom access log formats as well as a default format.