Access logging

Configuration

Access logs are configured as part of the HTTP connection manager config or TCP Proxy.

Format rules

The access log format string contains either command operators or other characters interpreted as a plain string. The access log formatter does not make any assumptions about a new line separator, so one has to specified as part of the format string. See the default format for an example. Note that the access log line will contain a ‘-‘ character for every not set/empty value.

The same format strings are used by different types of access logs (such as HTTP and TCP). Some fields may have slightly different meanings, depending on what type of log it is. Differences are noted.

The following command operators are supported:

%START_TIME%

  • HTTP

    Request start time including milliseconds.

    TCP

    Downstream connection start time including milliseconds.

START_TIME can be customized using a format string. In addition to that, START_TIME also accepts following specifiers:

SpecifierExplanation
%sThe number of seconds since the Epoch
%f, %[1-9]fFractional seconds digits, default is 9 digits (nanosecond)
  • %3f millisecond (3 digits)
  • %6f microsecond (6 digits)
  • %9f nanosecond (9 digits)

Examples of formatting START_TIME is as follows:

  1. %START_TIME(%Y/%m/%dT%H:%M:%S%z %s)%
  3. # To include millisecond fraction of the second (.000 ... .999). E.g. 1527590590.528.
  4. %START_TIME(%s.%3f)%
  6. %START_TIME(%s.%6f)%
  8. %START_TIME(%s.%9f)%

%BYTES_RECEIVED%

  • HTTP

    Body bytes received.

    TCP

    Downstream bytes received on connection.

%PROTOCOL%

  • HTTP

    Protocol. Currently either HTTP/1.1 or HTTP/2.

    TCP

    Not implemented (“-“).

%RESPONSE_CODE%

  • HTTP

    HTTP response code. Note that a response code of ‘0’ means that the server never sent the beginning of a response. This generally means that the (downstream) client disconnected.

    TCP

    Not implemented (“-“).

%BYTES_SENT%

  • HTTP

    Body bytes sent. For WebSocket connection it will also include response header bytes.

    TCP

    Downstream bytes sent on connection.

%DURATION%

  • HTTP

    Total duration in milliseconds of the request from the start time to the last byte out.

    TCP

    Total duration in milliseconds of the downstream connection.

%RESPONSE_FLAGS%

Additional details about the response or connection, if any. For TCP connections, the response codes mentioned in the descriptions do not apply. Possible values are:

  • HTTP and TCP

    • UH: No healthy upstream hosts in upstream cluster in addition to 503 response code.
    • UF: Upstream connection failure in addition to 503 response code.
    • UO: Upstream overflow (circuit breaking) in addition to 503 response code.
    • NR: No route configured for a given request in addition to 404 response code.

    HTTP only

    • LH: Local service failed health check request in addition to 503 response code.
    • UT: Upstream request timeout in addition to 504 response code.
    • LR: Connection local reset in addition to 503 response code.
    • UR: Upstream remote reset in addition to 503 response code.
    • UC: Upstream connection termination in addition to 503 response code.
    • DI: The request processing was delayed for a period specified via fault injection.
    • FI: The request was aborted with a response code specified via fault injection.
    • RL: The request was ratelimited locally by the HTTP rate limit filter in addition to 429 response code.

%UPSTREAM_HOST%

Upstream host URL (e.g., tcp://ip:port for TCP connections).

%UPSTREAM_CLUSTER%

Upstream cluster to which the upstream host belongs to.

%UPSTREAM_LOCAL_ADDRESS%

Local address of the upstream connection. If the address is an IP address it includes both address and port.

%DOWNSTREAM_REMOTE_ADDRESS%

Remote address of the downstream connection. If the address is an IP address it includes both address and port.

Note

This may not be the physical remote address of the peer if the address has been inferred from proxy proto or x-forwarded-for.

%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%

Remote address of the downstream connection. If the address is an IP address the output does not include port.

Note

This may not be the physical remote address of the peer if the address has been inferred from proxy proto or x-forwarded-for.

%DOWNSTREAM_LOCAL_ADDRESS%

Local address of the downstream connection. If the address is an IP address it includes both address and port. If the original connection was redirected by iptables REDIRECT, this represents the original destination address restored by the Original Destination Filter using SO_ORIGINAL_DST socket option. If the original connection was redirected by iptables TPROXY, and the listener’s transparent option was set to true, this represents the original destination address and port.

%DOWNSTREAM_LOCAL_ADDRESS_WITHOUT_PORT%

Same as %DOWNSTREAM_LOCAL_ADDRESS% excluding port if the address is an IP address.

%REQ(X?Y):Z%

  • HTTP

    An HTTP request header where X is the main HTTP header, Y is the alternative one, and Z is an optional parameter denoting string truncation up to Z characters long. The value is taken from the HTTP request header named X first and if it’s not set, then request header Y is used. If none of the headers are present ‘-‘ symbol will be in the log.

    TCP

    Not implemented (“-“).

%RESP(X?Y):Z%

  • HTTP

    Same as %REQ(X?Y):Z% but taken from HTTP response headers.

    TCP

    Not implemented (“-“).

%TRAILER(X?Y):Z%

  • HTTP

    Same as %REQ(X?Y):Z% but taken from HTTP response trailers.

    TCP

    Not implemented (“-“).

%DYNAMIC_METADATA(NAMESPACE:KEY*):Z%

  • HTTP

    Dynamic Metadata info, where NAMESPACE is the the filter namespace used when setting the metadata, KEY is an optional lookup up key in the namespace with the option of specifying nested keys separated by ‘:’, and Z is an optional parameter denoting string truncation up to Z characters long. Dynamic Metadata can be set by filters using the RequestInfo API: setDynamicMetadata. The data will be logged as a JSON string. For example, for the following dynamic metadata:

    com.test.my_filter: {"test_key": "foo", "test_object": {"inner_key": "bar"}}

    • %DYNAMIC_METADATA(com.test.my_filter)% will log: {"test_key": "foo", "test_object": {"inner_key": "bar"}}
    • %DYNAMIC_METADATA(com.test.my_filter:test_key)% will log: "foo"
    • %DYNAMIC_METADATA(com.test.my_filter:test_object)% will log: {"inner_key": "bar"}
    • %DYNAMIC_METADATA(com.test.my_filter:test_object:inner_key)% will log: "bar"
    • %DYNAMIC_METADATA(com.unknown_filter)% will log: -
    • %DYNAMIC_METADATA(com.test.my_filter:unknown_key)% will log: -
    • %DYNAMIC_METADATA(com.test.my_filter):25% will log (truncation at 25 characters): {"test_key": "foo", "test

    TCP

    Not implemented (“-“).

Default format

If custom format is not specified, Envoy uses the following default format:

  1. [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%"
  2. %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION%
  3. %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%"
  4. "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"\n

Example of the default Envoy access log format:

  1. [2016-04-15T20:17:00.310Z] "POST /api/v1/locations HTTP/2" 204 - 154 0 226 100 "10.0.35.28"
  2. "nsq2http" "cc21d9b0-cf5c-432b-8c7e-98aeb7988cd2" "locations" "tcp://10.0.2.1:80"