gRPC access logs¶

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:

data/accesslog/v2/accesslog.proto

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.

data.accesslog.v3.TCPAccessLogEntry¶

[data.accesslog.v3.TCPAccessLogEntry proto]

{
  "common_properties": "{...}",
  "connection_properties": "{...}"
}

common_properties: (data.accesslog.v3.AccessLogCommon) Common properties shared by all Envoy access logs.

connection_properties: (data.accesslog.v3.ConnectionProperties) Properties of the TCP connection.

data.accesslog.v3.HTTPAccessLogEntry¶

[data.accesslog.v3.HTTPAccessLogEntry proto]

{
  "common_properties": "{...}",
  "protocol_version": "...",
  "request": "{...}",
  "response": "{...}"
}

common_properties: (data.accesslog.v3.AccessLogCommon) Common properties shared by all Envoy access logs.

protocol_version: (data.accesslog.v3.HTTPAccessLogEntry.HTTPVersion)

request: (data.accesslog.v3.HTTPRequestProperties) Description of the incoming HTTP request.

response: (data.accesslog.v3.HTTPResponseProperties) Description of the outgoing HTTP response.

Enum data.accesslog.v3.HTTPAccessLogEntry.HTTPVersion¶

[data.accesslog.v3.HTTPAccessLogEntry.HTTPVersion proto]

HTTP version

PROTOCOL_UNSPECIFIED: (DEFAULT) ⁣

HTTP10: ⁣

HTTP11: ⁣

HTTP2: ⁣

HTTP3: ⁣

data.accesslog.v3.ConnectionProperties¶

[data.accesslog.v3.ConnectionProperties proto]

Defines fields for a connection

{
  "received_bytes": "...",
  "sent_bytes": "..."
}

received_bytes: (uint64) Number of bytes received from downstream.

sent_bytes: (uint64) Number of bytes sent to downstream.

data.accesslog.v3.AccessLogCommon¶

[data.accesslog.v3.AccessLogCommon proto]

Defines fields that are shared by all Envoy access logs.

{
  "downstream_remote_address": "{...}",
  "downstream_local_address": "{...}",
  "tls_properties": "{...}",
  "start_time": "{...}",
  "time_to_last_rx_byte": "{...}",
  "time_to_first_upstream_tx_byte": "{...}",
  "time_to_last_upstream_tx_byte": "{...}",
  "time_to_first_upstream_rx_byte": "{...}",
  "time_to_last_upstream_rx_byte": "{...}",
  "time_to_first_downstream_tx_byte": "{...}",
  "time_to_last_downstream_tx_byte": "{...}",
  "upstream_remote_address": "{...}",
  "upstream_local_address": "{...}",
  "upstream_cluster": "...",
  "response_flags": "{...}",
  "metadata": "{...}",
  "upstream_transport_failure_reason": "...",
  "route_name": "...",
  "downstream_direct_remote_address": "{...}",
  "filter_state_objects": "{...}",
  "custom_tags": "{...}"
}

downstream_remote_address: (config.core.v3.Address) This field is the remote/origin address on which the request from the user was received. Note: This may not be the physical peer. E.g, if the remote address is inferred from for example the x-forwarder-for header, proxy protocol, etc.

downstream_local_address: (config.core.v3.Address) This field is the local/destination address on which the request from the user was received.

tls_properties: (data.accesslog.v3.TLSProperties) If the connection is secure,S this field will contain TLS properties.

start_time: (Timestamp) The time that Envoy started servicing this request. This is effectively the time that the first downstream byte is received.

time_to_last_rx_byte: (Duration) Interval between the first downstream byte received and the last downstream byte received (i.e. time it takes to receive a request).

time_to_first_upstream_tx_byte: (Duration) Interval between the first downstream byte received and the first upstream byte sent. There may by considerable delta between time_to_last_rx_byte and this value due to filters. Additionally, the same caveats apply as documented in time_to_last_downstream_tx_byte about not accounting for kernel socket buffer time, etc.

time_to_last_upstream_tx_byte: (Duration) Interval between the first downstream byte received and the last upstream byte sent. There may by considerable delta between time_to_last_rx_byte and this value due to filters. Additionally, the same caveats apply as documented in time_to_last_downstream_tx_byte about not accounting for kernel socket buffer time, etc.

time_to_first_upstream_rx_byte: (Duration) Interval between the first downstream byte received and the first upstream byte received (i.e. time it takes to start receiving a response).

time_to_last_upstream_rx_byte: (Duration) Interval between the first downstream byte received and the last upstream byte received (i.e. time it takes to receive a complete response).

time_to_first_downstream_tx_byte: (Duration) Interval between the first downstream byte received and the first downstream byte sent. There may be a considerable delta between the time_to_first_upstream_rx_byte and this field due to filters. Additionally, the same caveats apply as documented in time_to_last_downstream_tx_byte about not accounting for kernel socket buffer time, etc.

time_to_last_downstream_tx_byte: (Duration) Interval between the first downstream byte received and the last downstream byte sent. Depending on protocol, buffering, windowing, filters, etc. there may be a considerable delta between time_to_last_upstream_rx_byte and this field. Note also that this is an approximate time. In the current implementation it does not include kernel socket buffer time. In the current implementation it also does not include send window buffering inside the HTTP/2 codec. In the future it is likely that work will be done to make this duration more accurate.

upstream_remote_address: (config.core.v3.Address) The upstream remote/destination address that handles this exchange. This does not include retries.

upstream_local_address: (config.core.v3.Address) The upstream local/origin address that handles this exchange. This does not include retries.

upstream_cluster: (string) The upstream cluster that upstream_remote_address belongs to.

response_flags: (data.accesslog.v3.ResponseFlags) Flags indicating occurrences during request/response processing.

metadata

(config.core.v3.Metadata) All metadata encountered during request processing, including endpoint selection.

This can be used to associate IDs attached to the various configurations used to process this request with the access log entry. For example, a route created from a higher level forwarding rule with some ID can place that ID in this field and cross reference later. It can also be used to determine if a canary endpoint was used or not.

upstream_transport_failure_reason: (string) If upstream connection failed due to transport socket (e.g. TLS handshake), provides the failure reason from the transport socket. The format of this field depends on the configured upstream transport socket. Common TLS failures are in TLS trouble shooting.

route_name: (string) The name of the route

downstream_direct_remote_address: (config.core.v3.Address) This field is the downstream direct remote address on which the request from the user was received. Note: This is always the physical peer, even if the remote address is inferred from for example the x-forwarder-for header, proxy protocol, etc.

filter_state_objects: (repeated map<string, Any>) Map of filter state in stream info that have been configured to be logged. If the filter state serialized to any message other than google.protobuf.Any it will be packed into google.protobuf.Any.

custom_tags: (repeated map<string, string>) A list of custom tags, which annotate logs with additional information. To configure this value, users should configure custom_tags.

data.accesslog.v3.ResponseFlags¶

[data.accesslog.v3.ResponseFlags proto]

Flags indicating occurrences during request/response processing.

{
  "failed_local_healthcheck": "...",
  "no_healthy_upstream": "...",
  "upstream_request_timeout": "...",
  "local_reset": "...",
  "upstream_remote_reset": "...",
  "upstream_connection_failure": "...",
  "upstream_connection_termination": "...",
  "upstream_overflow": "...",
  "no_route_found": "...",
  "delay_injected": "...",
  "fault_injected": "...",
  "rate_limited": "...",
  "unauthorized_details": "{...}",
  "rate_limit_service_error": "...",
  "downstream_connection_termination": "...",
  "upstream_retry_limit_exceeded": "...",
  "stream_idle_timeout": "...",
  "invalid_envoy_request_headers": "...",
  "downstream_protocol_error": "...",
  "upstream_max_stream_duration_reached": "...",
  "response_from_cache_filter": "...",
  "no_filter_config_found": "...",
  "duration_timeout": "...",
  "upstream_protocol_error": "...",
  "no_cluster_found": "...",
  "overload_manager": "...",
  "dns_resolution_failure": "..."
}

failed_local_healthcheck: (bool) Indicates local server healthcheck failed.

no_healthy_upstream: (bool) Indicates there was no healthy upstream.

upstream_request_timeout: (bool) Indicates an there was an upstream request timeout.

local_reset: (bool) Indicates local codec level reset was sent on the stream.

upstream_remote_reset: (bool) Indicates remote codec level reset was received on the stream.

upstream_connection_failure: (bool) Indicates there was a local reset by a connection pool due to an initial connection failure.

upstream_connection_termination: (bool) Indicates the stream was reset due to an upstream connection termination.

upstream_overflow: (bool) Indicates the stream was reset because of a resource overflow.

no_route_found: (bool) Indicates no route was found for the request.

delay_injected: (bool) Indicates that the request was delayed before proxying.

fault_injected: (bool) Indicates that the request was aborted with an injected error code.

rate_limited: (bool) Indicates that the request was rate-limited locally.

unauthorized_details: (data.accesslog.v3.ResponseFlags.Unauthorized) Indicates if the request was deemed unauthorized and the reason for it.

rate_limit_service_error: (bool) Indicates that the request was rejected because there was an error in rate limit service.

downstream_connection_termination: (bool) Indicates the stream was reset due to a downstream connection termination.

upstream_retry_limit_exceeded: (bool) Indicates that the upstream retry limit was exceeded, resulting in a downstream error.

stream_idle_timeout: (bool) Indicates that the stream idle timeout was hit, resulting in a downstream 408.

invalid_envoy_request_headers: (bool) Indicates that the request was rejected because an envoy request header failed strict validation.

downstream_protocol_error: (bool) Indicates there was an HTTP protocol error on the downstream request.

upstream_max_stream_duration_reached: (bool) Indicates there was a max stream duration reached on the upstream request.

response_from_cache_filter: (bool) Indicates the response was served from a cache filter.

no_filter_config_found: (bool) Indicates that a filter configuration is not available.

duration_timeout: (bool) Indicates that request or connection exceeded the downstream connection duration.

upstream_protocol_error: (bool) Indicates there was an HTTP protocol error in the upstream response.

no_cluster_found: (bool) Indicates no cluster was found for the request.

overload_manager: (bool) Indicates overload manager terminated the request.

dns_resolution_failure: (bool) Indicates a DNS resolution failed.

data.accesslog.v3.ResponseFlags.Unauthorized¶

[data.accesslog.v3.ResponseFlags.Unauthorized proto]

{
  "reason": "..."
}

reason: (data.accesslog.v3.ResponseFlags.Unauthorized.Reason)

Enum data.accesslog.v3.ResponseFlags.Unauthorized.Reason¶

[data.accesslog.v3.ResponseFlags.Unauthorized.Reason proto]

Reasons why the request was unauthorized

REASON_UNSPECIFIED: (DEFAULT) ⁣

EXTERNAL_SERVICE: ⁣The request was denied by the external authorization service.

data.accesslog.v3.TLSProperties¶

[data.accesslog.v3.TLSProperties proto]

Properties of a negotiated TLS connection.

{
  "tls_version": "...",
  "tls_cipher_suite": "{...}",
  "tls_sni_hostname": "...",
  "local_certificate_properties": "{...}",
  "peer_certificate_properties": "{...}",
  "tls_session_id": "..."
}

tls_version: (data.accesslog.v3.TLSProperties.TLSVersion) Version of TLS that was negotiated.

tls_cipher_suite

(UInt32Value) TLS cipher suite negotiated during handshake. The value is a four-digit hex code defined by the IANA TLS Cipher Suite Registry (e.g. 009C for TLS_RSA_WITH_AES_128_GCM_SHA256).

Here it is expressed as an integer.

tls_sni_hostname: (string) SNI hostname from handshake.

local_certificate_properties: (data.accesslog.v3.TLSProperties.CertificateProperties) Properties of the local certificate used to negotiate TLS.

peer_certificate_properties: (data.accesslog.v3.TLSProperties.CertificateProperties) Properties of the peer certificate used to negotiate TLS.

tls_session_id: (string) The TLS session ID.

data.accesslog.v3.TLSProperties.CertificateProperties¶

[data.accesslog.v3.TLSProperties.CertificateProperties proto]

{
  "subject_alt_name": [],
  "subject": "..."
}

subject_alt_name: (repeated data.accesslog.v3.TLSProperties.CertificateProperties.SubjectAltName) SANs present in the certificate.

subject: (string) The subject field of the certificate.

data.accesslog.v3.TLSProperties.CertificateProperties.SubjectAltName¶

[data.accesslog.v3.TLSProperties.CertificateProperties.SubjectAltName proto]

{
  "uri": "..."
}

uri: (string)

Enum data.accesslog.v3.TLSProperties.TLSVersion¶

[data.accesslog.v3.TLSProperties.TLSVersion proto]

VERSION_UNSPECIFIED: (DEFAULT) ⁣

TLSv1: ⁣

TLSv1_1: ⁣

TLSv1_2: ⁣

TLSv1_3: ⁣

data.accesslog.v3.HTTPRequestProperties¶

[data.accesslog.v3.HTTPRequestProperties proto]

{
  "request_method": "...",
  "scheme": "...",
  "authority": "...",
  "port": "{...}",
  "path": "...",
  "user_agent": "...",
  "referer": "...",
  "forwarded_for": "...",
  "request_id": "...",
  "original_path": "...",
  "request_headers_bytes": "...",
  "request_body_bytes": "...",
  "request_headers": "{...}"
}

request_method: (config.core.v3.RequestMethod) The request method (RFC 7231/2616).

scheme: (string) The scheme portion of the incoming request URI.

authority: (string) HTTP/2 :authority or HTTP/1.1 Host header value.

port: (UInt32Value) The port of the incoming request URI (unused currently, as port is composed onto authority).

path: (string) The path portion from the incoming request URI.

user_agent: (string) Value of the User-Agent request header.

referer: (string) Value of the Referer request header.

forwarded_for: (string) Value of the X-Forwarded-For request header.

request_id

(string) Value of the X-Request-Id request header

This header is used by Envoy to uniquely identify a request. It will be generated for all external requests and internal requests that do not already have a request ID.

original_path: (string) Value of the X-Envoy-Original-Path request header.

request_headers_bytes

(uint64) Size of the HTTP request headers in bytes.

This value is captured from the OSI layer 7 perspective, i.e. it does not include overhead from framing or encoding at other networking layers.

request_body_bytes

(uint64) Size of the HTTP request body in bytes.

This value is captured from the OSI layer 7 perspective, i.e. it does not include overhead from framing or encoding at other networking layers.

request_headers: (repeated map<string, string>) Map of additional headers that have been configured to be logged.

data.accesslog.v3.HTTPResponseProperties¶

[data.accesslog.v3.HTTPResponseProperties proto]

{
  "response_code": "{...}",
  "response_headers_bytes": "...",
  "response_body_bytes": "...",
  "response_headers": "{...}",
  "response_trailers": "{...}",
  "response_code_details": "..."
}

response_code: (UInt32Value) The HTTP response code returned by Envoy.

response_headers_bytes

(uint64) Size of the HTTP response headers in bytes.

This value is captured from the OSI layer 7 perspective, i.e. it does not include overhead from framing or encoding at other networking layers.

response_body_bytes

(uint64) Size of the HTTP response body in bytes.

This value is captured from the OSI layer 7 perspective, i.e. it does not include overhead from framing or encoding at other networking layers.

response_headers: (repeated map<string, string>) Map of additional headers configured to be logged.

response_trailers: (repeated map<string, string>) Map of trailers configured to be logged.

response_code_details: (string) The HTTP response code details.