.. _envoy_api_file_envoy/data/accesslog/v2/accesslog.proto: gRPC access logs ================ 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. .. _envoy_api_msg_data.accesslog.v2.HTTPAccessLogEntry: data.accesslog.v2.HTTPAccessLogEntry ------------------------------------ `[data.accesslog.v2.HTTPAccessLogEntry proto] `_ .. code-block:: json { "common_properties": "{...}", "protocol_version": "...", "request": "{...}", "response": "{...}" } .. _envoy_api_field_data.accesslog.v2.HTTPAccessLogEntry.common_properties: common_properties (:ref:`data.accesslog.v2.AccessLogCommon `) Common properties shared by all Envoy access logs. .. _envoy_api_field_data.accesslog.v2.HTTPAccessLogEntry.protocol_version: protocol_version (:ref:`data.accesslog.v2.HTTPAccessLogEntry.HTTPVersion `) .. _envoy_api_field_data.accesslog.v2.HTTPAccessLogEntry.request: request (:ref:`data.accesslog.v2.HTTPRequestProperties `) Description of the incoming HTTP request. .. _envoy_api_field_data.accesslog.v2.HTTPAccessLogEntry.response: response (:ref:`data.accesslog.v2.HTTPResponseProperties `) Description of the outgoing HTTP response. .. _envoy_api_enum_data.accesslog.v2.HTTPAccessLogEntry.HTTPVersion: Enum data.accesslog.v2.HTTPAccessLogEntry.HTTPVersion ----------------------------------------------------- `[data.accesslog.v2.HTTPAccessLogEntry.HTTPVersion proto] `_ HTTP version .. _envoy_api_enum_value_data.accesslog.v2.HTTPAccessLogEntry.HTTPVersion.PROTOCOL_UNSPECIFIED: PROTOCOL_UNSPECIFIED *(DEFAULT)* ⁣ .. _envoy_api_enum_value_data.accesslog.v2.HTTPAccessLogEntry.HTTPVersion.HTTP10: HTTP10 ⁣ .. _envoy_api_enum_value_data.accesslog.v2.HTTPAccessLogEntry.HTTPVersion.HTTP11: HTTP11 ⁣ .. _envoy_api_enum_value_data.accesslog.v2.HTTPAccessLogEntry.HTTPVersion.HTTP2: HTTP2 ⁣ .. _envoy_api_msg_data.accesslog.v2.AccessLogCommon: data.accesslog.v2.AccessLogCommon --------------------------------- `[data.accesslog.v2.AccessLogCommon proto] `_ Defines fields that are shared by all Envoy access logs. .. code-block:: json { "downstream_remote_address": "{...}", "downstream_local_address": "{...}", "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": "{...}" } .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.downstream_remote_address: downstream_remote_address (:ref:`core.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. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.downstream_local_address: downstream_local_address (:ref:`core.Address `) This field is the local/destination address on which the request from the user was received. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.start_time: start_time (`Timestamp `_) The time that Envoy started servicing this request. This is effectively the time that the first downstream byte is received. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.time_to_last_rx_byte: 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). .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.time_to_first_upstream_tx_byte: 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. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.time_to_last_upstream_tx_byte: 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. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.time_to_first_upstream_rx_byte: 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). .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.time_to_last_upstream_rx_byte: 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). .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.time_to_first_downstream_tx_byte: 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. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.time_to_last_downstream_tx_byte: 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. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.upstream_remote_address: upstream_remote_address (:ref:`core.Address `) The upstream remote/destination address that handles this exchange. This does not include retries. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.upstream_local_address: upstream_local_address (:ref:`core.Address `) The upstream local/origin address that handles this exchange. This does not include retries. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.upstream_cluster: upstream_cluster (`string `_) The upstream cluster that *upstream_remote_address* belongs to. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.response_flags: response_flags (:ref:`data.accesslog.v2.ResponseFlags `) Flags indicating occurrences during request/response processing. .. _envoy_api_field_data.accesslog.v2.AccessLogCommon.metadata: metadata (:ref:`core.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. .. _envoy_api_msg_data.accesslog.v2.ResponseFlags: data.accesslog.v2.ResponseFlags ------------------------------- `[data.accesslog.v2.ResponseFlags proto] `_ Flags indicating occurrences during request/response processing. .. code-block:: json { "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": "{...}", "downstream_connection_termination": "..." } .. _envoy_api_field_data.accesslog.v2.ResponseFlags.failed_local_healthcheck: failed_local_healthcheck (`bool `_) Indicates local server healthcheck failed. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.no_healthy_upstream: no_healthy_upstream (`bool `_) Indicates there was no healthy upstream. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.upstream_request_timeout: upstream_request_timeout (`bool `_) Indicates an there was an upstream request timeout. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.local_reset: local_reset (`bool `_) Indicates local codec level reset was sent on the stream. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.upstream_remote_reset: upstream_remote_reset (`bool `_) Indicates remote codec level reset was received on the stream. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.upstream_connection_failure: upstream_connection_failure (`bool `_) Indicates there was a local reset by a connection pool due to an initial connection failure. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.upstream_connection_termination: upstream_connection_termination (`bool `_) Indicates the stream was reset due to an upstream connection termination. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.upstream_overflow: upstream_overflow (`bool `_) Indicates the stream was reset because of a resource overflow. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.no_route_found: no_route_found (`bool `_) Indicates no route was found for the request. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.delay_injected: delay_injected (`bool `_) Indicates that the request was delayed before proxying. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.fault_injected: fault_injected (`bool `_) Indicates that the request was aborted with an injected error code. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.rate_limited: rate_limited (`bool `_) Indicates that the request was rate-limited locally. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.unauthorized_details: unauthorized_details (:ref:`data.accesslog.v2.ResponseFlags.Unauthorized `) Indicates if the request was deemed unauthorized and the reason for it. .. _envoy_api_field_data.accesslog.v2.ResponseFlags.downstream_connection_termination: downstream_connection_termination (`bool `_) Indicates the stream was reset due to a downstream connection termination. .. _envoy_api_msg_data.accesslog.v2.ResponseFlags.Unauthorized: data.accesslog.v2.ResponseFlags.Unauthorized -------------------------------------------- `[data.accesslog.v2.ResponseFlags.Unauthorized proto] `_ .. code-block:: json { "reason": "..." } .. _envoy_api_field_data.accesslog.v2.ResponseFlags.Unauthorized.reason: reason (:ref:`data.accesslog.v2.ResponseFlags.Unauthorized.Reason `) .. _envoy_api_enum_data.accesslog.v2.ResponseFlags.Unauthorized.Reason: Enum data.accesslog.v2.ResponseFlags.Unauthorized.Reason -------------------------------------------------------- `[data.accesslog.v2.ResponseFlags.Unauthorized.Reason proto] `_ Reasons why the request was unauthorized .. _envoy_api_enum_value_data.accesslog.v2.ResponseFlags.Unauthorized.Reason.REASON_UNSPECIFIED: REASON_UNSPECIFIED *(DEFAULT)* ⁣ .. _envoy_api_enum_value_data.accesslog.v2.ResponseFlags.Unauthorized.Reason.EXTERNAL_SERVICE: EXTERNAL_SERVICE ⁣The request was denied by the external authorization service. .. _envoy_api_msg_data.accesslog.v2.HTTPRequestProperties: data.accesslog.v2.HTTPRequestProperties --------------------------------------- `[data.accesslog.v2.HTTPRequestProperties proto] `_ .. code-block:: json { "request_method": "...", "scheme": "...", "authority": "...", "port": "{...}", "path": "...", "user_agent": "...", "referer": "...", "forwarded_for": "...", "request_id": "...", "original_path": "...", "request_headers_bytes": "...", "request_body_bytes": "...", "request_headers": "{...}" } .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.request_method: request_method (:ref:`core.RequestMethod `) The request method (RFC 7231/2616). .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.scheme: scheme (`string `_) The scheme portion of the incoming request URI. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.authority: authority (`string `_) HTTP/2 ``:authority`` or HTTP/1.1 ``Host`` header value. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.port: port (`UInt32Value `_) The port of the incoming request URI (unused currently, as port is composed onto authority). .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.path: path (`string `_) The path portion from the incoming request URI. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.user_agent: user_agent (`string `_) Value of the ``User-Agent`` request header. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.referer: referer (`string `_) Value of the ``Referer`` request header. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.forwarded_for: forwarded_for (`string `_) Value of the ``X-Forwarded-For`` request header. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.request_id: 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. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.original_path: original_path (`string `_) Value of the ``X-Envoy-Original-Path`` request header. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.request_headers_bytes: 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. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.request_body_bytes: 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. .. _envoy_api_field_data.accesslog.v2.HTTPRequestProperties.request_headers: request_headers (map<`string `_, `string `_>) Map of additional headers that have been configured to be logged. .. _envoy_api_msg_data.accesslog.v2.HTTPResponseProperties: data.accesslog.v2.HTTPResponseProperties ---------------------------------------- `[data.accesslog.v2.HTTPResponseProperties proto] `_ .. code-block:: json { "response_code": "{...}", "response_headers_bytes": "...", "response_body_bytes": "...", "response_headers": "{...}", "response_trailers": "{...}" } .. _envoy_api_field_data.accesslog.v2.HTTPResponseProperties.response_code: response_code (`UInt32Value `_) The HTTP response code returned by Envoy. .. _envoy_api_field_data.accesslog.v2.HTTPResponseProperties.response_headers_bytes: 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. .. _envoy_api_field_data.accesslog.v2.HTTPResponseProperties.response_body_bytes: 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. .. _envoy_api_field_data.accesslog.v2.HTTPResponseProperties.response_headers: response_headers (map<`string `_, `string `_>) Map of additional headers configured to be logged. .. _envoy_api_field_data.accesslog.v2.HTTPResponseProperties.response_trailers: response_trailers (map<`string `_, `string `_>) Map of trailers configured to be logged.