Expose trace sampling controls in the public API#375
Expose trace sampling controls in the public API#375hausdorff wants to merge 6 commits intoenvoyproxy:masterfrom
Conversation
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]: envoyproxy/envoy#1813
Signed-off-by: Alex Clemmer <clemmer.alexander@gmail.com>
effc535 to
2c4373d
Compare
|
@hausdorff thanks a bunch fo working on this. I think you actually want to add these options here https://github.com/envoyproxy/data-plane-api/blob/master/api/filter/network/http_connection_manager.proto#L67 which is per HTTP connection manager config. If you look at how they will actually be used, the function is here: https://github.com/envoyproxy/envoy/blob/master/source/common/tracing/http_tracer_impl.cc#L43. This ends up being called from the connection manager and will require the connection manager config getting plumbed through. |
|
@mattklein123 Ok cool, thanks for the quick review, I'll update this PR later today. |
Following up from Matt Klein's comments that they should be customizable on a per-conn-manager basis. Signed-off-by: Alex Clemmer <clemmer.alexander@gmail.com>
| // 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]; |
There was a problem hiding this comment.
You will need to use wrapped types, i.e. google.protobuf.UInt32Value, to obtain the defaulting behavior specified in https://www.envoyproxy.io/docs/envoy/latest/configuration/http_conn_man/runtime.html?highlight=sample. This is because proto3 can't distinguish between non-specified scalar values and their null values (0 in the case of uint32).
There was a problem hiding this comment.
Ok, so just so we're all clear, you're saying they need to be nullable so that we can detect when they're not set when we plumb it through to the runtime? (EDIT: I now see that they're not nullable, but they're null-check-able. Heh.)
Makes sense. Fixed.
|
|
||
| // 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. |
There was a problem hiding this comment.
This is a problem in runtime as well, but I can't help but feel that we should have a standard practice for specifying percentages in the Envoy proto API. In some places, we use double, other places uint32, with different degrees of granularity. Ideally we would have a Percent message type in the API that would also capture the lte constraint.
@mattklein123 @wora for comment and possible addition to STYLE.md. I don't think there is anything actionable for this PR @hausdorff.
There was a problem hiding this comment.
+1. I'm sad we didn't do this in the original v2 conversion. Oh well. Might as well start now. Can we just add a common Percent message per @htuch? I would probably just use a double and clamp it between 0.0 and 1.0. Internally, we can convert to integer as needed (e.g., a number out of 10,000 or 100,000 or whatever).
There was a problem hiding this comment.
I didn't want to cause waves by having the API not match up with the implementation, but I'd also prefer the wrapping a double in a Percent message type. So let's do that.
Fixed.
| // 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. |
There was a problem hiding this comment.
Please specify the default as done in https://www.envoyproxy.io/docs/envoy/latest/configuration/http_conn_man/runtime.html?highlight=sample.
| 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 |
There was a problem hiding this comment.
The convention we have for headers in docs is *x-client-trace-id*.
| // 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 |
There was a problem hiding this comment.
Consider linking back and forth between these docs and https://www.envoyproxy.io/docs/envoy/latest/configuration/http_conn_man/runtime.html?highlight=sample.
There was a problem hiding this comment.
Originally I didn't because this link went stale in the original issue, but we can add it if you like.
Signed-off-by: Alex Clemmer <clemmer.alexander@gmail.com>
|
@mattklein123, @htuch Ok, so we've created a new message type, BTW I took a guess about how we want to handle the resolution mismatch of using a |
htuch
left a comment
There was a problem hiding this comment.
Great, thanks for the Percent cleanup. Unfortunately, we can't go and change existing uses of Percent variants where APIs are frozen, since this will break backwards compatibility. So, we can only use this in new fields or some of the experimental APIs. See https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/v2_overview#status for what is frozen/experimental.
api/base.proto
Outdated
| } | ||
|
|
||
| message Percent { | ||
| float value = 5 [(validate.rules).float = {gte: 0, lte: 100}]; |
There was a problem hiding this comment.
float value = 1 would be more minimal. One other thing; I think @mattklein123 was suggesting we make this between 0.0 and 1.0.
There was a problem hiding this comment.
ah, sorry, I got lazy. Will fix.
api/base.proto
Outdated
| google.protobuf.Struct config = 2; | ||
| } | ||
|
|
||
| message Percent { |
There was a problem hiding this comment.
Can you add some simple comment for docs purposes (e.g. explaining purpose, valid ranges).
| // <https://www.envoyproxy.io/docs/envoy/latest/configuration/http_conn_man/runtime.html?highlight=sample>`_. | ||
| Percent global_enabled = 4; | ||
|
|
||
| // Global target percentage of requests that will be randomly traced. Must be a number between 0 |
There was a problem hiding this comment.
The range comments here can be elided if we add them to Percent.
| // 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 | ||
| // <https://www.envoyproxy.io/docs/envoy/latest/configuration/http_conn_man/runtime.html?highlight=sample>`_. |
There was a problem hiding this comment.
You can do :ref: style internal links to avoid relying on possible stale external links, grep around for how :ref: is used to see how.
Signed-off-by: Alex Clemmer <clemmer.alexander@gmail.com>
htuch
left a comment
There was a problem hiding this comment.
Thanks! You'll need to run the fix_format script as the check_format is failing before we can merge.
Signed-off-by: Alex Clemmer <clemmer.alexander@gmail.com>
3f18342 to
6938a37
Compare
|
@htuch ah, sorry, I thought I read in the style guide we're wrapping at 100 columns. |
| 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., |
There was a problem hiding this comment.
For new things in the v2 API, I think we have the chance to normalize the gradients which will be much less confusing to people. I would recommend doing the following:
- Documenting on the Percent message itself that the float value will be normalized to 0.01% increments. (Internally we will multiply by 10,000).
- Then we can remove the rounding documentation from each of these such that it's inferred that everything is 0.01% increments.
For legacy code in which a Percent object is not defined, we can use the legacy runtime dividend. For code in which Percent is defined, we can use 10,000 as the dividend. I would recommend we also deprecate the old dividends that are not 100 in runtime and then just delete them in the next release with a release note.
I realize this is more work, but it will make the future situation much easier to understand.
How does this sound?
There was a problem hiding this comment.
(I'm pretty easy-going about landing the patches correctly even if it's slower.)
I am ok with having all Percent objects resolve at 0.01% increments as long as @htuch agrees. But while it's up in the air, I'm a bit confused about the semantics.
What's the reason we're using an integral type instead of a float-ish type to represent stuff like sampling percentage targets? Is it just to force people to think in target percentages that are perceptibly different over a few thousand requests? If so then representing it as a float just seems like a weird tool, since we're letting people express things we won't execute on. (EDIT: Especially since it's possible to have something weird like 1.0000000001 or something, which I suspect would fail the bounds check above.)
And if not, then I'm not sure an arbitrary truncation horizon is clearly better than just letting good old IEEE 754 "solve" the problem incidentally by the way it specifies float semantics.
There was a problem hiding this comment.
There is no good historical reason that the config didn't always use floats. It's just the way it was done. Internally in the code, dealing with integers is substantially faster when computing randomness and random chance hits, so we want to be able to convert any float config into integers for computation.
I actually don't care if we want to make Percent very clearly an integer between 0 and 10,000 and explain that it will be converted to 0.01% increments internally. I just figured most users would prefer to work with a float. I'm fine either way.
@wora might have some thoughts on this as well. I would prefer to wait for him to chime in before we merge this so it will likely need to wait till early next week.
There was a problem hiding this comment.
P.S., the reason 10,000 is used is that random result can be inferred from 2 bytes of entropy which we make use of in a few places (UUID stable sampling comes to mind).
There was a problem hiding this comment.
Agreed. There should be no rush on API changes!
There was a problem hiding this comment.
In general, we should avoid using float unless it is data size critical, such as colors. JSON cannot represent float, so you end up float<->double conversions everywhere, and causes data loss.
Envoy is a basic infrastructure. So I don't feel Envoy should enforces the minimum ratio of 0.01%. Why is this something Envoy needs to decide? Can we leave the problem to the operators.
If we do enforces 0.01% ratio, then we should change Percent to use integers, so we don't need to explain the rounding problem because integer forces rounding anyway.
There was a problem hiding this comment.
How about changing Percent to RoundedPercent so it's more clear to the user? We can also switch to double and make the range 0.0-100.0 per @wora. Then I think there will be no confusion that we are going to round internally for performance reasons.
There was a problem hiding this comment.
We don't need, and will likely never need, the extra resolution, but it's also not a big deal to just use double. Let's go with double.
api/base.proto
Outdated
| // <envoy_api_field_filter.network.HttpConnectionManager.tracing>`). | ||
| message Percent { | ||
| // The percent, a float between 0 and 1. | ||
| float value = 1 [(validate.rules).float = {gte: 0, lte: 1}]; |
There was a problem hiding this comment.
I would also say that I don't feel very strongly about 0.0-1.0 if people prefer 0.0-100.0.
There was a problem hiding this comment.
I prefer ~0.0-~1.0, which I think most people would say is more intuitive.
I would consider replacing 1.0 with some other number (e.g., 100) if we were planning on users needing that extra resolution between numbers. I do not get the sense they will, though.
There was a problem hiding this comment.
If the message is called percent, the value range should be [0, 100]. That is how most people interpret English words.
There was a problem hiding this comment.
SGTM, I think per above we should switch to RoundedPercent, double, 0.0-100.0
|
The current design probably makes sense for Envoy developers. I don't think it is suitable for operators who want to use the feature. The design enforces too many restrictions and terminology on operators. IMO, tracing is not a mission critical feature like authz, we should let operators control whatever they want. There is no need for us to enforce too much rules, such as the percent rounding. |
api/base.proto
Outdated
| // <envoy_api_field_filter.network.HttpConnectionManager.tracing>`). | ||
| message Percent { | ||
| // The percent, a float between 0 and 1. | ||
| float value = 1 [(validate.rules).float = {gte: 0, lte: 1}]; |
There was a problem hiding this comment.
If the message is called percent, the value range should be [0, 100]. That is how most people interpret English words.
| 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., |
There was a problem hiding this comment.
In general, we should avoid using float unless it is data size critical, such as colors. JSON cannot represent float, so you end up float<->double conversions everywhere, and causes data loss.
Envoy is a basic infrastructure. So I don't feel Envoy should enforces the minimum ratio of 0.01%. Why is this something Envoy needs to decide? Can we leave the problem to the operators.
If we do enforces 0.01% ratio, then we should change Percent to use integers, so we don't need to explain the rounding problem because integer forces rounding anyway.
| // same name in the :ref:`HTTP Connection Manager <config_http_conn_man_runtime>`. | ||
| Percent global_enabled = 4; | ||
|
|
||
| // Global target percentage of requests that will be randomly traced. Percent is resolved to the |
There was a problem hiding this comment.
The concept of Global is strange here. If I run a server, that server can be a standalone server, or a server in a cluster, or a zone, or a region, or many regions. What does "Global" mean here? Does my server have to talk to a global service to do the tracing?
There was a problem hiding this comment.
Nope, it's per HTTP connection manager (as I understand it). Fixed.
| 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 |
There was a problem hiding this comment.
We really should get out of the rounding business. If I am running a memcache service with millions of requests per second, why do I have to follow such policy?
There was a problem hiding this comment.
The API docs are telling you what Envoy itself is going to do. We need to explain to users of the API what the effect of setting a specific value will have, so somewhere we need to be clear about how fine grained percentages/ratios will be interpreted in practice.
| // 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 <config_http_conn_man_runtime>`. | ||
| Percent global_enabled = 4; |
There was a problem hiding this comment.
We should not design an API based on another API unless the concept is well know, such as country_code. From reading this comment, I don't understand what "global enabled" means to me, either as a developer or an operator.
There was a problem hiding this comment.
Yup let's clean this up. Let's just call this sampled to go with client_sampled above.
| // Connection Manager <config_http_conn_man_runtime>`. | ||
| Percent client_enabled = 3; | ||
|
|
||
| // Global target percentage of requests that will be traced after all other checks have been |
There was a problem hiding this comment.
The concept of "after all other checks" is questionable here. In a distributed system, we can not assume there is a fixed order of checks. It doesn't seem proper to assume tracing has the privilege of being the last decider.
There was a problem hiding this comment.
My understanding is that this is per-HTTP connection manager, which is not distributed, so I think we should just get rid of the "global" and call that out specifically.
|
|
||
| // 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 |
There was a problem hiding this comment.
My personal lesson with infrastructure design is everything should be default to 0. Don't assume everyone wants my feature no matter how much I love it myself.
If I add a new feature to a system, I cannot touch all existing customers, so the new feature must be default off. Instead of arguing whether a new feature should be default on, we should have a hard policy, everything is default off, and don't spend time debating on it. We never know what users want to do.
There was a problem hiding this comment.
Although I agree that default 0 would be better, that's not how the current code works and we can't change it. Se la vi.
| // 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 <config_http_conn_man_runtime>`. | ||
| Percent client_enabled = 3; |
There was a problem hiding this comment.
The field name is very vague. It is more like "client_enabled_sampling".
There was a problem hiding this comment.
Agreed. This was an unfortunate internal name choice. Let's fix this in the config. I would probably just do client_sampling personally.
|
Ok, let me try to summarize current open issues, so they don't get lost:
I'll fix (1). For (2), I agree with @mattklein123 that it's probably too late to change the sampling defaults, since they're baked into HTTP Connection Manager's runtime. I'll update the code and mark this as resolved since I sense this is not up for debate. :) So I think the only remaining issue is (3). I agree there is a tension between how percentages are expressed and how we represent them for performance reasons. I think, on balance, if we're not going to actually use |
|
Personally, I still feel there is value in a common |
|
@mattklein123, @htuch, @wora I've resolved 2 of the 3 open issues in the summary. For the third, in the new commit, I'm proposing that we have I will admit to being a little peeved that we're using a double for the ones-rounded percentages, but then again, if I wanted to work on something pretty, I would still be working in math. |
Signed-off-by: Alex Clemmer <clemmer.alexander@gmail.com>
0d1642e to
bec964a
Compare
|
If we enforce rounding, then float and double doesn't make much difference.
When I suggest to use double, my concern was related to float<->double
loss. Since float can handle 0.01% accurately, I don't think it matter as
much.
|
| // 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 | ||
| // <config_http_conn_man_runtime>`. | ||
| double client_sampling = 3 [(validate.rules).double = {gte: 0, lte: 100}]; |
There was a problem hiding this comment.
I think we should do the following:
- Add a universal
Percentmessage, which enforced [0..100] range and is backed bydouble. - Express locally, at each field, what the actual effective interpretation will be. This interpretation might change over time (e.g. it might be rounded to nearest 1% today, in later Envoy releases it might be 0.1%). I agree with @wora that folks supplying the API data should be able to express their intents as fine grained as they wish, but at the same time, users need to know what the limits at the implementation level are.
| // 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 <config_http_conn_man_runtime>`. | ||
| double sampling = 4 [(validate.rules).double = {gte: 0, lte: 100}]; |
There was a problem hiding this comment.
Can you start a STYLE.md in root with a single bullet point for now, which captures the point that @wora made about preferring double over float for JSON conversion reasons? This is is something we should now start to be more consistent about, and it's one of these missing proto3 style guidelines that would be good to codify. Thanks!
|
Let's not to put hundredth percent into the message name. We may allow finer grained control in the future. We just document it in the comments. This is a subtle trade off we often need to make: code vs comment. It is much easier to add features and update the comment. We should codify the spec if there is strong need for it. In this case, I think it is just an optimization, so we don't need to codify it IMO. |
htuch
left a comment
There was a problem hiding this comment.
Removing approval until changes made to make PR status overview easier to understand.
|
@hausdorff FYI, in case it's useful, there's now a |
|
@hausdorff friendly ping. |
|
@hausdorff I'm going to close this out due to inactivity, feel free to reopen when you want to resume. |
|
@htuch I was just about to comment that I was really hoping this could go in, as we need it in Istio. Is the only thing left to cleanup the PR description? Shall I duplicate the current state with a clearer description in a separate PR? How can I best move this forward? |
|
Yeah, it's good to go if we can update it to use the new |
I'm basically completely new to Envoy, so I am probably missing some stuff you'd want to see in a PR, just let me know and I'll fix it up.
Additional questions I think I've answered, but might be worth double-checking:
Envoy core has an open issue1 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.
requests to be force-traced. (Meant to map to HTTP connection
manager's runtime tracing.client_enabled setting.)
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.)
be randomly traced. (Meant to map to HTTP connection manager's
runtime tracing.random_sampling setting.)
Signed-off-by: Alex Clemmer clemmer.alexander@gmail.com