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]

{
  "name": "...",
  "filter": "{...}",
  "config": "{...}"
}

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]

{
  "status_code_filter": "{...}",
  "duration_filter": "{...}",
  "not_health_check_filter": "{...}",
  "traceable_filter": "{...}",
  "runtime_filter": "{...}",
  "and_filter": "{...}",
  "or_filter": "{...}"
}

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.

{
  "op": "...",
  "value": "{...}"
}

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.

{
  "comparison": "{...}"
}

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.

{
  "comparison": "{...}"
}

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.

{}

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.

{}

config.filter.accesslog.v2.RuntimeFilter¶

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

Filters for random sampling of requests.

{
  "runtime_key": "...",
  "percent_sampled": "{...}",
  "use_independent_randomness": "..."
}

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.

{
  "filters": []
}

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.

{
  "filters": []
}

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.

{
  "path": "...",
  "format": "..."
}

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.