access log service: cleanup and docs (#3494)
Fixes https://github.com/envoyproxy/envoy/issues/743 This is a general cleanup of all of the access logging documentation. I have reorganized a bunch of things and hidden the various gRPC logging fields that are not implemented yet. I've also moved the existing tap protos into a new "output" directory. This is the best name I could come up for cleanly separating output data that might be stored outside of any service or configuration. Signed-off-by: Matt Klein <mklein@lyft.com> Mirrored from https://github.com/envoyproxy/envoy @ c15019e79c832d9f0a09468affaadabc4be3e115pull/620/head
data-plane-api(CircleCI)
7 years ago
parent
87b2671ef0
commit
22a5c5ba09
17 changed files with 394 additions and 338 deletions
@ -0,0 +1,21 @@ |
||||
syntax = "proto3"; |
||||
|
||||
package envoy.config.accesslog.v2; |
||||
option go_package = "v2"; |
||||
|
||||
import "validate/validate.proto"; |
||||
|
||||
// [#protodoc-title: File access log] |
||||
|
||||
// Custom configuration for an :ref:`AccessLog <envoy_api_msg_config.filter.accesslog.v2.AccessLog>` |
||||
// that writes log entries directly to a file. Configures the built-in *envoy.file_access_log* |
||||
// AccessLog. |
||||
message FileAccessLog { |
||||
// A path to a local file to which to write the access log entries. |
||||
string path = 1 [(validate.rules).string.min_bytes = 1]; |
||||
|
||||
// Access log format. Envoy supports :ref:`custom access log formats |
||||
// <config_access_log_format>` as well as a :ref:`default format |
||||
// <config_access_log_default_format>`. |
||||
string format = 2; |
||||
} |
||||
@ -0,0 +1,24 @@ |
||||
load("//bazel:api_build_system.bzl", "api_go_proto_library", "api_proto_library") |
||||
|
||||
licenses(["notice"]) # Apache 2 |
||||
|
||||
api_proto_library( |
||||
name = "accesslog", |
||||
srcs = ["accesslog.proto"], |
||||
visibility = [ |
||||
"//envoy/service/accesslog/v2:__pkg__", |
||||
], |
||||
deps = [ |
||||
"//envoy/api/v2/core:address", |
||||
"//envoy/api/v2/core:base", |
||||
], |
||||
) |
||||
|
||||
api_go_proto_library( |
||||
name = "accesslog", |
||||
proto = ":accesslog", |
||||
deps = [ |
||||
"//envoy/api/v2/core:address_go_proto", |
||||
"//envoy/api/v2/core:base_go_proto", |
||||
], |
||||
) |
||||
@ -0,0 +1,288 @@ |
||||
syntax = "proto3"; |
||||
|
||||
package envoy.data.accesslog.v2; |
||||
|
||||
import "envoy/api/v2/core/address.proto"; |
||||
import "envoy/api/v2/core/base.proto"; |
||||
|
||||
import "google/protobuf/duration.proto"; |
||||
import "google/protobuf/timestamp.proto"; |
||||
import "google/protobuf/wrappers.proto"; |
||||
import "gogoproto/gogo.proto"; |
||||
import "validate/validate.proto"; |
||||
|
||||
// [#protodoc-title: 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. |
||||
|
||||
// [#not-implemented-hide:] |
||||
message TCPAccessLogEntry { |
||||
// Common properties shared by all Envoy access logs. |
||||
AccessLogCommon common_properties = 1; |
||||
} |
||||
|
||||
message HTTPAccessLogEntry { |
||||
// Common properties shared by all Envoy access logs. |
||||
AccessLogCommon common_properties = 1; |
||||
|
||||
// HTTP version |
||||
enum HTTPVersion { |
||||
PROTOCOL_UNSPECIFIED = 0; |
||||
HTTP10 = 1; |
||||
HTTP11 = 2; |
||||
HTTP2 = 3; |
||||
} |
||||
HTTPVersion protocol_version = 2; |
||||
|
||||
// Description of the incoming HTTP request. |
||||
HTTPRequestProperties request = 3; |
||||
|
||||
// Description of the outgoing HTTP response. |
||||
HTTPResponseProperties response = 4; |
||||
} |
||||
|
||||
// Defines fields that are shared by all Envoy access logs. |
||||
message AccessLogCommon { |
||||
// [#not-implemented-hide:] |
||||
// This field indicates the rate at which this log entry was sampled. |
||||
// Valid range is (0.0, 1.0]. |
||||
double sample_rate = 1 [(validate.rules).double.gt = 0.0, (validate.rules).double.lte = 1.0]; |
||||
|
||||
// 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.v2.core.Address downstream_remote_address = 2; |
||||
|
||||
// This field is the local/destination address on which the request from the user was received. |
||||
envoy.api.v2.core.Address downstream_local_address = 3; |
||||
|
||||
// [#not-implemented-hide:] |
||||
// If the connection is secure,S this field will contain TLS properties. |
||||
TLSProperties tls_properties = 4; |
||||
|
||||
// The time that Envoy started servicing this request. This is effectively the time that the first |
||||
// downstream byte is received. |
||||
google.protobuf.Timestamp start_time = 5 [(gogoproto.stdtime) = true]; |
||||
|
||||
// Interval between the first downstream byte received and the last |
||||
// downstream byte received (i.e. time it takes to receive a request). |
||||
google.protobuf.Duration time_to_last_rx_byte = 6 [(gogoproto.stdduration) = true]; |
||||
|
||||
// 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. |
||||
google.protobuf.Duration time_to_first_upstream_tx_byte = 7 [(gogoproto.stdduration) = true]; |
||||
|
||||
// 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. |
||||
google.protobuf.Duration time_to_last_upstream_tx_byte = 8 [(gogoproto.stdduration) = true]; |
||||
|
||||
// Interval between the first downstream byte received and the first upstream |
||||
// byte received (i.e. time it takes to start receiving a response). |
||||
google.protobuf.Duration time_to_first_upstream_rx_byte = 9 [(gogoproto.stdduration) = true]; |
||||
|
||||
// Interval between the first downstream byte received and the last upstream |
||||
// byte received (i.e. time it takes to receive a complete response). |
||||
google.protobuf.Duration time_to_last_upstream_rx_byte = 10 [(gogoproto.stdduration) = true]; |
||||
|
||||
// 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. |
||||
google.protobuf.Duration time_to_first_downstream_tx_byte = 11 [(gogoproto.stdduration) = true]; |
||||
|
||||
// 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. |
||||
google.protobuf.Duration time_to_last_downstream_tx_byte = 12 [(gogoproto.stdduration) = true]; |
||||
|
||||
// The upstream remote/destination address that handles this exchange. This does not include |
||||
// retries. |
||||
envoy.api.v2.core.Address upstream_remote_address = 13; |
||||
|
||||
// The upstream local/origin address that handles this exchange. This does not include retries. |
||||
envoy.api.v2.core.Address upstream_local_address = 14; |
||||
|
||||
// The upstream cluster that *upstream_remote_address* belongs to. |
||||
string upstream_cluster = 15; |
||||
|
||||
// Flags indicating occurrences during request/response processing. |
||||
ResponseFlags response_flags = 16; |
||||
|
||||
// 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.v2.core.Metadata metadata = 17; |
||||
} |
||||
|
||||
// Flags indicating occurrences during request/response processing. |
||||
message ResponseFlags { |
||||
// Indicates local server healthcheck failed. |
||||
bool failed_local_healthcheck = 1; |
||||
|
||||
// Indicates there was no healthy upstream. |
||||
bool no_healthy_upstream = 2; |
||||
|
||||
// Indicates an there was an upstream request timeout. |
||||
bool upstream_request_timeout = 3; |
||||
|
||||
// Indicates local codec level reset was sent on the stream. |
||||
bool local_reset = 4; |
||||
|
||||
// Indicates remote codec level reset was received on the stream. |
||||
bool upstream_remote_reset = 5; |
||||
|
||||
// Indicates there was a local reset by a connection pool due to an initial connection failure. |
||||
bool upstream_connection_failure = 6; |
||||
|
||||
// Indicates the stream was reset locally due to connection termination. |
||||
bool upstream_connection_termination = 7; |
||||
|
||||
// Indicates the stream was reset because of a resource overflow. |
||||
bool upstream_overflow = 8; |
||||
|
||||
// Indicates no route was found for the request. |
||||
bool no_route_found = 9; |
||||
|
||||
// Indicates that the request was delayed before proxying. |
||||
bool delay_injected = 10; |
||||
|
||||
// Indicates that the request was aborted with an injected error code. |
||||
bool fault_injected = 11; |
||||
|
||||
// Indicates that the request was rate-limited locally. |
||||
bool rate_limited = 12; |
||||
|
||||
message Unauthorized { |
||||
// Reasons why the request was unauthorized |
||||
enum Reason { |
||||
REASON_UNSPECIFIED = 0; |
||||
// The request was denied by the external authorization service. |
||||
EXTERNAL_SERVICE = 1; |
||||
} |
||||
|
||||
Reason reason = 1; |
||||
} |
||||
|
||||
// Indicates if the request was deemed unauthorized and the reason for it. |
||||
Unauthorized unauthorized_details = 13; |
||||
} |
||||
|
||||
// [#not-implemented-hide:] |
||||
// Properties of a negotiated TLS connection. |
||||
message TLSProperties { |
||||
enum TLSVersion { |
||||
VERSION_UNSPECIFIED = 0; |
||||
TLSv1 = 1; |
||||
TLSv1_1 = 2; |
||||
TLSv1_2 = 3; |
||||
TLSv1_3 = 4; |
||||
} |
||||
// Version of TLS that was negotiated. |
||||
TLSVersion tls_version = 1; |
||||
|
||||
// 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. |
||||
google.protobuf.UInt32Value tls_cipher_suite = 2; |
||||
|
||||
// SNI hostname from handshake. |
||||
string tls_sni_hostname = 3; |
||||
} |
||||
|
||||
message HTTPRequestProperties { |
||||
// The request method (RFC 7231/2616). |
||||
// [#comment:TODO(htuch): add (validate.rules).enum.defined_only = true once |
||||
// https://github.com/lyft/protoc-gen-validate/issues/42 is resolved.] |
||||
envoy.api.v2.core.RequestMethod request_method = 1; |
||||
|
||||
// The scheme portion of the incoming request URI. |
||||
string scheme = 2; |
||||
|
||||
// HTTP/2 ``:authority`` or HTTP/1.1 ``Host`` header value. |
||||
string authority = 3; |
||||
|
||||
// The port of the incoming request URI |
||||
// (unused currently, as port is composed onto authority). |
||||
google.protobuf.UInt32Value port = 4; |
||||
|
||||
// The path portion from the incoming request URI. |
||||
string path = 5; |
||||
|
||||
// Value of the ``User-Agent`` request header. |
||||
string user_agent = 6; |
||||
|
||||
// Value of the ``Referer`` request header. |
||||
string referer = 7; |
||||
|
||||
// Value of the ``X-Forwarded-For`` request header. |
||||
string forwarded_for = 8; |
||||
|
||||
// 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. |
||||
string request_id = 9; |
||||
|
||||
// Value of the ``X-Envoy-Original-Path`` request header. |
||||
string original_path = 10; |
||||
|
||||
// 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. |
||||
uint64 request_headers_bytes = 11; |
||||
|
||||
// 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. |
||||
uint64 request_body_bytes = 12; |
||||
|
||||
// Map of additional headers that have been configured to be logged. |
||||
map<string, string> request_headers = 13; |
||||
} |
||||
|
||||
message HTTPResponseProperties { |
||||
// The HTTP response code returned by Envoy. |
||||
google.protobuf.UInt32Value response_code = 1; |
||||
|
||||
// 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. |
||||
uint64 response_headers_bytes = 2; |
||||
|
||||
// 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. |
||||
uint64 response_body_bytes = 3; |
||||
|
||||
// Map of additional headers configured to be logged. |
||||
map<string, string> response_headers = 4; |
||||
|
||||
// Map of trailers configured to be logged. |
||||
map<string, string> response_trailers = 5; |
||||
} |
||||
Loading…
Reference in new issue