From 2c4373d9d6ce3e43a3bc54c0adfc8b7af408671d Mon Sep 17 00:00:00 2001 From: Alex Clemmer Date: Fri, 29 Dec 2017 15:09:43 -0700 Subject: [PATCH 1/6] Expose trace sampling controls in the public API Envoy core has an open issue[1] to expose the target trace sample percentages as part of the API. This is exposed as part of the HTTP connection manager runtime, but is not yet exposed as part of the API. (See the issue for more details on those controls.) This commit will introduce the 3 main runtime controls as part of the core API. 1. Tracing#client_enabled, which specifies the target percentage of requests to be force-traced. (Meant to map to HTTP connection manager's runtime tracing.client_enabled setting.) 2. Tracing#global_enabled, which specifies the target percentage of requests to be traced after all rules and checks have been applied. (Meant to map to HTTP connection manager's runtime tracing.global_enabled setting.) 3. Tracing#random_sampling, which specifies the number of requests to be randomly traced. (Meant to map to HTTP connection manager's runtime tracing.random_sampling setting.) [1]: https://github.com/envoyproxy/envoy/issues/1813 Signed-off-by: Alex Clemmer --- api/trace.proto | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/api/trace.proto b/api/trace.proto index ca5a2d3aa..d645d258f 100644 --- a/api/trace.proto +++ b/api/trace.proto @@ -29,6 +29,22 @@ message Tracing { } // Provides configuration for the HTTP tracer. Http http = 1; + + // Global target percentage of requests that will be force traced if the + // x-client-trace-id header is set. Must be an integer number between 0 and + // 100. + uint32 client_enabled = 2 [(validate.rules).uint32.lte = 100]; + + // Global target percentage of requests that will be traced after all other + // checks have been applied (force tracing, sampling, etc.). Must be a number + // between 0 and + // 100. + uint32 global_enabled = 3 [(validate.rules).uint32.lte = 100]; + + // Global target percentage of requests that will be randomly traced. + // Specified as ten-thousandths of a percent (i.e., in 0.01% increments), + // using integer numbers in the range 0-10000. + uint32 random_sampling = 4 [(validate.rules).uint32.lte = 10000]; } // Configuration for the LightStep tracer. From 33e1cea02c32ccbf79d4f77c6446987e4e1dfdcc Mon Sep 17 00:00:00 2001 From: Alex Clemmer Date: Fri, 29 Dec 2017 18:30:41 -0700 Subject: [PATCH 2/6] Move the trace sampling controls to HttpConnectionManager Following up from Matt Klein's comments that they should be customizable on a per-conn-manager basis. Signed-off-by: Alex Clemmer --- api/filter/network/http_connection_manager.proto | 16 ++++++++++++++++ api/trace.proto | 16 ---------------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/api/filter/network/http_connection_manager.proto b/api/filter/network/http_connection_manager.proto index f442a617a..3111110f2 100644 --- a/api/filter/network/http_connection_manager.proto +++ b/api/filter/network/http_connection_manager.proto @@ -80,6 +80,22 @@ message HttpConnectionManager { // populate the tag name, and the header value is used to populate the tag value. The tag is // created if the specified header name is present in the request's headers. repeated string request_headers_for_tags = 2; + + // Global target percentage of requests that will be force traced if the + // x-client-trace-id header is set. Must be an integer number between 0 and + // 100. + uint32 client_enabled = 3 [(validate.rules).uint32.lte = 100]; + + // Global target percentage of requests that will be traced after all other + // checks have been applied (force tracing, sampling, etc.). Must be a + // number between 0 and + // 100. + uint32 global_enabled = 4 [(validate.rules).uint32.lte = 100]; + + // Global target percentage of requests that will be randomly traced. + // Specified as ten-thousandths of a percent (i.e., in 0.01% increments), + // using integer numbers in the range 0-10000. + uint32 random_sampling = 5 [(validate.rules).uint32.lte = 10000]; } // Presence of the object defines whether the connection manager diff --git a/api/trace.proto b/api/trace.proto index d645d258f..ca5a2d3aa 100644 --- a/api/trace.proto +++ b/api/trace.proto @@ -29,22 +29,6 @@ message Tracing { } // Provides configuration for the HTTP tracer. Http http = 1; - - // Global target percentage of requests that will be force traced if the - // x-client-trace-id header is set. Must be an integer number between 0 and - // 100. - uint32 client_enabled = 2 [(validate.rules).uint32.lte = 100]; - - // Global target percentage of requests that will be traced after all other - // checks have been applied (force tracing, sampling, etc.). Must be a number - // between 0 and - // 100. - uint32 global_enabled = 3 [(validate.rules).uint32.lte = 100]; - - // Global target percentage of requests that will be randomly traced. - // Specified as ten-thousandths of a percent (i.e., in 0.01% increments), - // using integer numbers in the range 0-10000. - uint32 random_sampling = 4 [(validate.rules).uint32.lte = 10000]; } // Configuration for the LightStep tracer. From 2ebd52ab0969defeb84395040484b9e3d53f1b03 Mon Sep 17 00:00:00 2001 From: Alex Clemmer Date: Sat, 30 Dec 2017 01:44:19 -0700 Subject: [PATCH 3/6] Use dedicated Percentage message type for percentages Signed-off-by: Alex Clemmer --- api/base.proto | 4 +++ .../network/http_connection_manager.proto | 34 +++++++++++-------- 2 files changed, 23 insertions(+), 15 deletions(-) diff --git a/api/base.proto b/api/base.proto index 2c4b5ff31..6515385f0 100644 --- a/api/base.proto +++ b/api/base.proto @@ -227,3 +227,7 @@ message TransportSocket { // See the supported transport socket implementations for further documentation. google.protobuf.Struct config = 2; } + +message Percent { + float value = 5 [(validate.rules).float = {gte: 0, lte: 100}]; +} diff --git a/api/filter/network/http_connection_manager.proto b/api/filter/network/http_connection_manager.proto index 3111110f2..77b13af73 100644 --- a/api/filter/network/http_connection_manager.proto +++ b/api/filter/network/http_connection_manager.proto @@ -81,21 +81,25 @@ message HttpConnectionManager { // created if the specified header name is present in the request's headers. repeated string request_headers_for_tags = 2; - // Global target percentage of requests that will be force traced if the - // x-client-trace-id header is set. Must be an integer number between 0 and - // 100. - uint32 client_enabled = 3 [(validate.rules).uint32.lte = 100]; - - // Global target percentage of requests that will be traced after all other - // checks have been applied (force tracing, sampling, etc.). Must be a - // number between 0 and - // 100. - uint32 global_enabled = 4 [(validate.rules).uint32.lte = 100]; - - // Global target percentage of requests that will be randomly traced. - // Specified as ten-thousandths of a percent (i.e., in 0.01% increments), - // using integer numbers in the range 0-10000. - uint32 random_sampling = 5 [(validate.rules).uint32.lte = 10000]; + // Global target percentage of requests that will be force traced if the *x-client-trace-id* + // header is set. Must be an number between 0 and 100; resolution is to the nearest 1% (rounded + // down). Defaults to 100. This variable is a direct analog for the variable of the same name in + // the `HTTP Connection Manager + // `_. + Percent client_enabled = 3; + + // Global target percentage of requests that will be traced after all other checks have been + // applied (force tracing, sampling, etc.). Must be a number between 0 and 100; resolution is to + // the nearest 1% (rounded down). Defaults to 100. This variable is a direct analog for the + // variable of the same name in the `HTTP Connection Manager + // `_. + Percent global_enabled = 4; + + // Global target percentage of requests that will be randomly traced. Must be a number between 0 + // and 100; resolution is to the nearest 0.01%, rounded down. Defaults to 100. This variable is + // a direct analog for the variable of the same name in the `HTTP Connection Manager + // `_. + Percent random_sampling = 5; } // Presence of the object defines whether the connection manager From 5f4defede038941bd637a725893d06828ac87b11 Mon Sep 17 00:00:00 2001 From: Alex Clemmer Date: Sat, 30 Dec 2017 12:03:33 -0700 Subject: [PATCH 4/6] Small documentation fixes Signed-off-by: Alex Clemmer --- api/base.proto | 6 +++++- .../network/http_connection_manager.proto | 21 ++++++++----------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/api/base.proto b/api/base.proto index 6515385f0..4b401351d 100644 --- a/api/base.proto +++ b/api/base.proto @@ -228,6 +228,10 @@ message TransportSocket { google.protobuf.Struct config = 2; } +// Percent, typically used to specify things like target sampling percentages among tracing requests +// (as in, e.g., :ref:`HTTP Connection Manager tracing +// `). message Percent { - float value = 5 [(validate.rules).float = {gte: 0, lte: 100}]; + // The percent, a float between 0 and 1. + float value = 1 [(validate.rules).float = {gte: 0, lte: 1}]; } diff --git a/api/filter/network/http_connection_manager.proto b/api/filter/network/http_connection_manager.proto index 77b13af73..58a73fbd8 100644 --- a/api/filter/network/http_connection_manager.proto +++ b/api/filter/network/http_connection_manager.proto @@ -82,23 +82,20 @@ message HttpConnectionManager { repeated string request_headers_for_tags = 2; // Global target percentage of requests that will be force traced if the *x-client-trace-id* - // header is set. Must be an number between 0 and 100; resolution is to the nearest 1% (rounded - // down). Defaults to 100. This variable is a direct analog for the variable of the same name in - // the `HTTP Connection Manager - // `_. + // header is set. Percent is resolved to the nearest 1% (rounded down). Defaults to 1 (i.e., 100%). This + // variable is a direct analog for the variable of the same name in the :ref:`HTTP Connection + // Manager `. Percent client_enabled = 3; // Global target percentage of requests that will be traced after all other checks have been - // applied (force tracing, sampling, etc.). Must be a number between 0 and 100; resolution is to - // the nearest 1% (rounded down). Defaults to 100. This variable is a direct analog for the - // variable of the same name in the `HTTP Connection Manager - // `_. + // applied (force tracing, sampling, etc.). Percent is resolved to the nearest 1% (rounded + // down). Defaults to 1 (i.e., 100%). This variable is a direct analog for the variable of the same name in + // the :ref:`HTTP Connection Manager `. Percent global_enabled = 4; - // Global target percentage of requests that will be randomly traced. Must be a number between 0 - // and 100; resolution is to the nearest 0.01%, rounded down. Defaults to 100. This variable is - // a direct analog for the variable of the same name in the `HTTP Connection Manager - // `_. + // Global target percentage of requests that will be randomly traced. Percent is resolved to the + // nearest 0.01%, rounded down. Defaults to 1 (i.e., 100%). This variable is a direct analog for + // the variable of the same name in the :ref:`HTTP Connection Manager `. Percent random_sampling = 5; } From 6938a37550f0370bc3d69feda7b05725cb52d8d1 Mon Sep 17 00:00:00 2001 From: Alex Clemmer Date: Sat, 30 Dec 2017 15:35:44 -0700 Subject: [PATCH 5/6] Docs fixes Signed-off-by: Alex Clemmer --- api/filter/network/http_connection_manager.proto | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/api/filter/network/http_connection_manager.proto b/api/filter/network/http_connection_manager.proto index 58a73fbd8..8b42df964 100644 --- a/api/filter/network/http_connection_manager.proto +++ b/api/filter/network/http_connection_manager.proto @@ -82,20 +82,21 @@ message HttpConnectionManager { repeated string request_headers_for_tags = 2; // Global target percentage of requests that will be force traced if the *x-client-trace-id* - // header is set. Percent is resolved to the nearest 1% (rounded down). Defaults to 1 (i.e., 100%). This - // variable is a direct analog for the variable of the same name in the :ref:`HTTP Connection - // Manager `. + // header is set. Percent is resolved to the nearest 1% (rounded down). Defaults to 1 (i.e., + // 100%). This variable is a direct analog for the variable of the same name in the :ref:`HTTP + // Connection Manager `. Percent client_enabled = 3; // Global target percentage of requests that will be traced after all other checks have been // applied (force tracing, sampling, etc.). Percent is resolved to the nearest 1% (rounded - // down). Defaults to 1 (i.e., 100%). This variable is a direct analog for the variable of the same name in - // the :ref:`HTTP Connection Manager `. + // down). Defaults to 1 (i.e., 100%). This variable is a direct analog for the variable of the + // same name in the :ref:`HTTP Connection Manager `. Percent global_enabled = 4; // Global target percentage of requests that will be randomly traced. Percent is resolved to the // nearest 0.01%, rounded down. Defaults to 1 (i.e., 100%). This variable is a direct analog for - // the variable of the same name in the :ref:`HTTP Connection Manager `. + // the variable of the same name in the :ref:`HTTP Connection Manager + // `. Percent random_sampling = 5; } From bec964aaaf974a2c27fd5ccc1a15f9123c5aaf4b Mon Sep 17 00:00:00 2001 From: Alex Clemmer Date: Tue, 2 Jan 2018 19:22:53 -0700 Subject: [PATCH 6/6] Update documentation and percent data types Signed-off-by: Alex Clemmer --- api/base.proto | 10 +++---- .../network/http_connection_manager.proto | 29 +++++++++---------- 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/api/base.proto b/api/base.proto index 4b401351d..736cb3270 100644 --- a/api/base.proto +++ b/api/base.proto @@ -228,10 +228,10 @@ message TransportSocket { google.protobuf.Struct config = 2; } -// Percent, typically used to specify things like target sampling percentages among tracing requests -// (as in, e.g., :ref:`HTTP Connection Manager tracing +// A percent, rounded down to the nearest 0.01%. Typically used to specify things like target +// sampling percentages among tracing requests (as in, e.g., :ref:`HTTP Connection Manager tracing // `). -message Percent { - // The percent, a float between 0 and 1. - float value = 1 [(validate.rules).float = {gte: 0, lte: 1}]; +message HundredthsRoundedPercent { + // The percent, a float between 0 and 100. Rounded to the nearest 0.01%. + double value = 1 [(validate.rules).double = {gte: 0, lte: 100}]; } diff --git a/api/filter/network/http_connection_manager.proto b/api/filter/network/http_connection_manager.proto index 8b42df964..c73f3e68d 100644 --- a/api/filter/network/http_connection_manager.proto +++ b/api/filter/network/http_connection_manager.proto @@ -81,23 +81,22 @@ message HttpConnectionManager { // created if the specified header name is present in the request's headers. repeated string request_headers_for_tags = 2; - // Global target percentage of requests that will be force traced if the *x-client-trace-id* - // header is set. Percent is resolved to the nearest 1% (rounded down). Defaults to 1 (i.e., - // 100%). This variable is a direct analog for the variable of the same name in the :ref:`HTTP - // Connection Manager `. - Percent client_enabled = 3; + // Target percentage of requests managed by this HTTP connectionmanager that will be force + // traced if the *x-client-trace-id* header is set. Defaults to 100%. This variable is a direct + // analog for the variable of the same name in the :ref:`HTTP Connection Manager + // `. + double client_sampling = 3 [(validate.rules).double = {gte: 0, lte: 100}]; - // Global target percentage of requests that will be traced after all other checks have been - // applied (force tracing, sampling, etc.). Percent is resolved to the nearest 1% (rounded - // down). Defaults to 1 (i.e., 100%). This variable is a direct analog for the variable of the - // same name in the :ref:`HTTP Connection Manager `. - Percent global_enabled = 4; + // Target percentage of requests managed by this HTTP connection manager that will be traced + // after all other checks have been applied (force tracing, sampling, etc.). Defaults to 100%. + // This variable is a direct analog for the variable of the same name in the :ref:`HTTP + // Connection Manager `. + double sampling = 4 [(validate.rules).double = {gte: 0, lte: 100}]; - // Global target percentage of requests that will be randomly traced. Percent is resolved to the - // nearest 0.01%, rounded down. Defaults to 1 (i.e., 100%). This variable is a direct analog for - // the variable of the same name in the :ref:`HTTP Connection Manager - // `. - Percent random_sampling = 5; + // Target percentage of requests managed by this HTTP connection manager that will be randomly + // traced. Defaults to 100%. This variable is a direct analog for the variable of the same name + // in the :ref:`HTTP Connection Manager `. + HundredthsRoundedPercent random_sampling = 5; } // Presence of the object defines whether the connection manager