diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index d366ff93df9..e00124b49f2 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) @@ -116,7 +117,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. @@ -132,6 +133,10 @@ The use cases of this are: Returns list of fields that will be used by the `TextMapPropagator`. +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 Injects the value into a carrier. The required arguments are the same as defined by @@ -180,7 +185,23 @@ 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` method as described below. +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 +expose corresponding methods as delegates or other ways. + +##### 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 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