From 6e3e1a784cc583f1fe1a7fd3ed109a8f54e0b1b4 Mon Sep 17 00:00:00 2001 From: Stephan Zuercher Date: Fri, 27 Oct 2017 12:40:00 -0700 Subject: [PATCH] api: router upstream log (#211) Signed-off-by: Stephan Zuercher --- api/filter/BUILD | 11 ++ api/filter/accesslog.proto | 110 ++++++++++++++++++ api/filter/http/BUILD | 2 + api/filter/http/http_connection_manager.proto | 103 +--------------- api/filter/http/router.proto | 7 ++ 5 files changed, 131 insertions(+), 102 deletions(-) create mode 100644 api/filter/accesslog.proto diff --git a/api/filter/BUILD b/api/filter/BUILD index 1b82e00d..a361c540 100644 --- a/api/filter/BUILD +++ b/api/filter/BUILD @@ -7,11 +7,14 @@ licenses(["notice"]) # Apache 2 proto_library( name = "go_protos", srcs = [ + "accesslog.proto", "fault.proto", ], visibility = ["//visibility:public"], deps = [ + "//api:go_protos", "@com_google_protobuf//:duration_proto", + "@com_google_protobuf//:struct_proto", ], ) @@ -21,7 +24,9 @@ go_proto_library( proto = ":go_protos", visibility = ["//visibility:public"], deps = [ + "//api:go_default_library", "@com_github_golang_protobuf//ptypes/duration:go_default_library", + "@com_github_golang_protobuf//ptypes/struct:go_default_library", ], ) @@ -29,3 +34,9 @@ api_proto_library( name = "fault", srcs = ["fault.proto"], ) + +api_proto_library( + name = "accesslog", + srcs = ["accesslog.proto"], + deps = ["//api:base"], +) diff --git a/api/filter/accesslog.proto b/api/filter/accesslog.proto new file mode 100644 index 00000000..ee099c9f --- /dev/null +++ b/api/filter/accesslog.proto @@ -0,0 +1,110 @@ +syntax = "proto3"; + +package envoy.api.v2.filter; + +import "api/base.proto"; + +import "google/protobuf/struct.proto"; + +// Filter on some integer comparison. +message ComparisonFilter { + // Comparison operator. + enum Op { + EQ = 0; + GE = 1; + } + Op op = 1; + + // Value to compare against. + RuntimeUInt32 value = 2; +} + +// Filters on HTTP response/status code. +message StatusCodeFilter { + ComparisonFilter comparison = 1; +} + +// Filters on total request duration in milliseconds. +message DurationFilter { + ComparisonFilter comparison = 1; +} + +// Filters for requests that are not health check requests. A health check +// request is marked by the health check filter. +message NotHealthCheckFilter { +} + +// Filters for requests that are traceable. See the tracing overview for more +// information on how a request becomes traceable. +message TraceableFilter { +} + +// Filters for random sampling of requests. 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, the filter will +// randomly sample based on the runtime key value. +message RuntimeFilter { + // Runtime key to get the percentage of requests to be sampled. This runtime + // control is specified in the range 0-100 and defaults to 0. + string runtime_key = 1; +} + +// 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. +message AndFilter { + repeated AccessLogFilter filters = 1; +} + +// 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. +message OrFilter { + repeated AccessLogFilter filters = 2; +} + +message AccessLogFilter { + oneof filter_specifier { + StatusCodeFilter status_code_filter = 1; + DurationFilter duration_filter = 2; + NotHealthCheckFilter not_health_check_filter = 3; + TraceableFilter traceable_filter = 4; + RuntimeFilter runtime_filter = 5; + AndFilter and_filter = 6; + OrFilter or_filter = 7; + } +} + +// Custom configuration for an 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; + + // [V2-API-DIFF] In addition to the existing format specifiers, the following + // additional specifiers will be available: + // %TLS_SNI_HOSTNAME%: SNI from handshake. + // %TLS_VERSION%: Possible values include: “TLSv1”, “TLSv1.1”, + // “TLSv1.2”, “TLSv1.3”. + // %TLS_CIPHER_SUITE%: Cipher suite negotiated during the TLS handshake. The + // value is four hex digits defined by the IANA TLS Cipher Suite Registry, + // e.g. “009C” for TLS_RSA_WITH_AES_128_GCM_SHA256. + // TODO(htuch): Document how envoy.http_connection_manager.access_log values + // can be accessed in the format specifier. + string format = 2; +} + +message AccessLog { + // The name of the access log implementation to instantiate. The name must + // match a statically registered access log. + string name = 1; + + // Filter which is used to determine if the access log needs to be written. + AccessLogFilter filter = 2; + + // Custom configuration that depends on the access log being instantiated. + // See the supported AccessLogs for further documentation. + google.protobuf.Struct config = 3; +} + diff --git a/api/filter/http/BUILD b/api/filter/http/BUILD index d3baf67f..9e3e2fc8 100644 --- a/api/filter/http/BUILD +++ b/api/filter/http/BUILD @@ -54,12 +54,14 @@ api_proto_library( "//api:base", "//api:protocol", "//api:rds", + "//api/filter:accesslog", ], ) api_proto_library( name = "router", srcs = ["router.proto"], + deps = ["//api/filter:accesslog"], ) api_proto_library( diff --git a/api/filter/http/http_connection_manager.proto b/api/filter/http/http_connection_manager.proto index 0dda6d3a..016d92bc 100644 --- a/api/filter/http/http_connection_manager.proto +++ b/api/filter/http/http_connection_manager.proto @@ -6,6 +6,7 @@ option go_package = "http"; import "api/base.proto"; import "api/protocol.proto"; import "api/rds.proto"; +import "api/filter/accesslog.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/struct.proto"; @@ -22,108 +23,6 @@ message Rds { string route_config_name = 2; } -// Filter on some integer comparison. -message ComparisonFilter { - // Comparison operator. - enum Op { - EQ = 0; - GE = 1; - } - Op op = 1; - - // Value to compare against. - RuntimeUInt32 value = 2; -} - -// Filters on HTTP response/status code. -message StatusCodeFilter { - ComparisonFilter comparison = 1; -} - -// Filters on total request duration in milliseconds. -message DurationFilter { - ComparisonFilter comparison = 1; -} - -// Filters for requests that are not health check requests. A health check -// request is marked by the health check filter. -message NotHealthCheckFilter { -} - -// Filters for requests that are traceable. See the tracing overview for more -// information on how a request becomes traceable. -message TraceableFilter { -} - -// Filters for random sampling of requests. 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, the filter will -// randomly sample based on the runtime key value. -message RuntimeFilter { - // Runtime key to get the percentage of requests to be sampled. This runtime - // control is specified in the range 0-100 and defaults to 0. - string runtime_key = 1; -} - -// 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. -message AndFilter { - repeated AccessLogFilter filters = 1; -} - -// 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. -message OrFilter { - repeated AccessLogFilter filters = 2; -} - -message AccessLogFilter { - oneof filter_specifier { - StatusCodeFilter status_code_filter = 1; - DurationFilter duration_filter = 2; - NotHealthCheckFilter not_health_check_filter = 3; - TraceableFilter traceable_filter = 4; - RuntimeFilter runtime_filter = 5; - AndFilter and_filter = 6; - OrFilter or_filter = 7; - } -} - -// Custom configuration for an 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; - - // [V2-API-DIFF] In addition to the existing format specifiers, the following - // additional specifiers will be available: - // %TLS_SNI_HOSTNAME%: SNI from handshake. - // %TLS_VERSION%: Possible values include: “TLSv1”, “TLSv1.1”, - // “TLSv1.2”, “TLSv1.3”. - // %TLS_CIPHER_SUITE%: Cipher suite negotiated during the TLS handshake. The - // value is four hex digits defined by the IANA TLS Cipher Suite Registry, - // e.g. “009C” for TLS_RSA_WITH_AES_128_GCM_SHA256. - // TODO(htuch): Document how envoy.http_connection_manager.access_log values - // can be accessed in the format specifier. - string format = 2; -} - -message AccessLog { - // The name of the access log implementation to instantiate. The name must - // match a statically registered access log. - string name = 1; - - // Filter which is used to determine if the access log needs to be written. - AccessLogFilter filter = 2; - - // Custom configuration that depends on the access log being instantiated. - // See the supported AccessLogs for further documentation. - google.protobuf.Struct config = 3; -} - message HttpFilter { // The name of the filter to instantiate. The name must match a supported // filter. diff --git a/api/filter/http/router.proto b/api/filter/http/router.proto index 2644ebca..600c7f1c 100644 --- a/api/filter/http/router.proto +++ b/api/filter/http/router.proto @@ -2,6 +2,8 @@ syntax = "proto3"; package envoy.api.v2.filter.http; +import "api/filter/accesslog.proto"; + import "google/protobuf/wrappers.proto"; // The router filter implements HTTP forwarding. It will be used in almost @@ -18,4 +20,9 @@ message Router { // outbound calls and have child spans rooted at the same ingress // parent. Defaults to false. bool start_child_span = 2; + // Configuration for HTTP upstream logs emitted by the router. Upstream logs + // are configured in the same way as access logs, but each log entry represents + // an upstream request. Presuming retries are configured, multiple upstream + // requests may be made for each downstream (inbound) request. + repeated AccessLog upstream_log = 3; }