From c3fecad95c1ed4e5497f7371b926dff04c5237bd Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 18 Aug 2020 14:50:34 +0200 Subject: [PATCH 1/4] Add of Getter's Keys operation. --- specification/context/api-propagators.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index cc6d0e45429..0f02c234539 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -18,6 +18,7 @@ Table of Contents - [Set](#set) - [Extract](#extract-1) - [Getter argument](#getter-argument) + - [Keys](#keys) - [Get](#get) - [Composite Propagator](#composite-propagator) - [Global Propagators](#global-propagators) @@ -113,7 +114,7 @@ avoid runtime allocations. ### Fields -The propagation fields defined. If your carrier is reused, you should delete the fields here +The predefined propagation fields. If your carrier is reused, you should delete the fields here before calling [inject](#inject). Fields are defined as string keys identifying format-specific components in a carrier. @@ -129,6 +130,9 @@ The use cases of this are: Returns list of fields that will be used by the `HttpTextPropagator`. +Observe that some `Propagator`s may define additional fields with variable names, such +as fields with different names simply sharing the `jaeger-` prefix. + ### Inject Injects the value into a carrier. The required arguments are the same as defined by @@ -177,7 +181,20 @@ Getter is an argument in `Extract` that get value from given field `Getter` allows a `HttpTextPropagator` to read propagated fields from a carrier. -One of the ways to implement it is `Getter` class with `Get` method as described below. +One of the ways to implement it is `Getter` class with `Get` and `Keys` methods +as described below. + +##### Keys + +The Keys function MUST return the list of all the keys in the carrier. + +Required arguments: + +- The carrier of the propagation fields, such as an HTTP request. + +The Keys function can be called by `Propagator`s using variable key names in order to +iterate over the entire keys in the specified carrier. For example, it can be used to +detect all keys starting with the prefix `jaeger-`. ##### Get From d49d197021d7a835f855a78235eb8ccd001271dd Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 19 Aug 2020 21:25:47 +0200 Subject: [PATCH 2/4] Apply feedback. --- specification/context/api-propagators.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 0f02c234539..af9f92b6cbd 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -130,8 +130,9 @@ The use cases of this are: Returns list of fields that will be used by the `HttpTextPropagator`. -Observe that some `Propagator`s may define additional fields with variable names, such -as fields with different names simply sharing the `jaeger-` prefix. +Observe that some `Propagator`s may define, besides the returned values, additional fields with +variable names. To get a full list of fields for a specific carrier object, use the +[Keys](#keys) operation. ### Inject @@ -186,15 +187,17 @@ as described below. ##### Keys -The Keys function MUST return the list of all the keys in the carrier. +The `Keys` function MUST return the list of all the keys in the carrier. Required arguments: -- The carrier of the propagation fields, such as an HTTP request. +- The carrier of the propagation fields, such as an HTTP request. -The Keys function can be called by `Propagator`s using variable key names in order to -iterate over the entire keys in the specified carrier. For example, it can be used to -detect all keys starting with the prefix `jaeger-`. +The `Keys` function can be called by `Propagator`s which are using variable key names in order to +iterate over all the keys in the specified carrier. + +For example, it can be used to detect all keys following the `uberctx-{user-defined-key}` pattern, as defined by the +[Jaeger Propagation Format](https://www.jaegertracing.io/docs/1.18/client-libraries/#baggage). ##### Get From ed1973aeec86ced5002c7315aaff6368155690cd Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 21 Aug 2020 16:33:33 +0200 Subject: [PATCH 3/4] Update specification/context/api-propagators.md Co-authored-by: Sergey Kanzhelev --- specification/context/api-propagators.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index af9f92b6cbd..f19dfd398ae 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -183,7 +183,8 @@ Getter is an argument in `Extract` that get value from given field `Getter` allows a `HttpTextPropagator` to read propagated fields from a carrier. One of the ways to implement it is `Getter` class with `Get` and `Keys` methods -as described below. +as described below. Languages may decide on alternative implementations and +expose corresponding methods as delegates or other ways. ##### Keys From 4e4c20e925f11037b2852442ed19af0b17e2b50d Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Sat, 22 Aug 2020 14:46:56 +0200 Subject: [PATCH 4/4] Remove extra trailing space. --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index cc659ed2442..e00124b49f2 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -186,7 +186,7 @@ Getter is an argument in `Extract` that get value from given field `Getter` allows a `TextMapPropagator` to read propagated fields from a carrier. One of the ways to implement it is `Getter` class with `Get` and `Keys` methods -as described below. Languages may decide on alternative implementations and +as described below. Languages may decide on alternative implementations and expose corresponding methods as delegates or other ways. ##### Keys