From 839f6692c021c2ae82dd55eefeb15a732b4684ce Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 12 Aug 2020 21:25:07 +0200 Subject: [PATCH 1/6] Rename HTTPText to Text Propagator. --- specification/context/api-propagators.md | 16 ++++++++-------- specification/overview.md | 2 +- specification/trace/api.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index b9cd3fc9e19..54037747722 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -11,7 +11,7 @@ Table of Contents - [Operations](#operations) - [Inject](#inject) - [Extract](#extract) -- [HTTPText Propagator](#httptext-propagator) +- [Text Propagator](#text-propagator) - [Fields](#fields) - [Inject](#inject-1) - [Setter argument](#setter-argument) @@ -49,7 +49,7 @@ and is bound to a data type, in order to propagate in-band context data across p The Propagators API currently defines one `Propagator` type: -- `HTTPTextPropagator` is a type that inject values into and extracts values +- `TextPropagator` is a type that inject values into and extracts values from carriers as string key/value pairs. A binary `Propagator` type will be added in the future (see [#437](https://github.com/open-telemetry/opentelemetry-specification/issues/437)). @@ -95,9 +95,9 @@ Returns a new `Context` derived from the `Context` passed as argument, containing the extracted value, which can be a `SpanContext`, `CorrelationContext` or another cross-cutting concern context. -## HTTPText Propagator +## Text Propagator -`HTTPTextPropagator` performs the injection and extraction of a cross-cutting concern +`TextPropagator` performs the injection and extraction of a cross-cutting concern value as string key/values pairs into carriers that travel in-band across process boundaries. The carrier of propagated data on both the client (injector) and server (extractor) side is @@ -127,7 +127,7 @@ The use cases of this are: - allow pre-allocation of fields, especially in systems like gRPC Metadata - allow a single-pass over an iterator -Returns list of fields that will be used by the `HttpTextPropagator`. +Returns list of fields that will be used by the `TextPropagator`. ### Inject @@ -143,7 +143,7 @@ Optional arguments: Setter is an argument in `Inject` that sets values into given fields. -`Setter` allows a `HttpTextPropagator` to set propagated fields into a carrier. +`Setter` allows a `TextPropagator` to set propagated fields into a carrier. One of the ways to implement it is `Setter` class with `Set` method as described below. @@ -175,7 +175,7 @@ Returns a new `Context` derived from the `Context` passed as argument. Getter is an argument in `Extract` that get value from given field -`Getter` allows a `HttpTextPropagator` to read propagated fields from a carrier. +`Getter` allows a `TextPropagator` to read propagated fields from a carrier. One of the ways to implement it is `Getter` class with `Get` method as described below. @@ -208,7 +208,7 @@ A composite propagator can be built from a list of propagators, or a list of injectors and extractors. The resulting composite `Propagator` will invoke the `Propagator`s, `Injector`s, or `Extractor`s, in the order they were specified. Each composite `Propagator` will implement a specific `Propagator` type, such -as `HttpTextPropagator`, as different `Propagator` types will likely operate on different +as `TextPropagator`, as different `Propagator` types will likely operate on different data types. There MUST be functions to accomplish the following operations. diff --git a/specification/overview.md b/specification/overview.md index cdc6d2be2ae..182f6a2cb3c 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -247,7 +247,7 @@ imposed by a specific transport and bound to a data type. The Propagators API currently defines one `Propagator` type: -- `HTTPTextPropagator` injects values into and extracts values from carriers as text. +- `TextPropagator` injects values into and extracts values from carriers as text. ## Collector diff --git a/specification/trace/api.md b/specification/trace/api.md index 1c574fb1fa7..07993c870a4 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -693,4 +693,4 @@ implementer of these links. The API layer MAY include the following `Propagator`s: -* A `HTTPTextPropagator` implementing the [W3C TraceContext Specification](https://www.w3.org/TR/trace-context/). +* A `TextPropagator` implementing the [W3C TraceContext Specification](https://www.w3.org/TR/trace-context/). From 2b6c0c5d2213425b1fafa03c57e63562d93036aa Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 19 Aug 2020 23:34:39 +0200 Subject: [PATCH 2/6] Use TextMapPropagator instead. --- specification/context/api-propagators.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 54037747722..f71cb227c08 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -11,7 +11,7 @@ Table of Contents - [Operations](#operations) - [Inject](#inject) - [Extract](#extract) -- [Text Propagator](#text-propagator) +- [TextMap Propagator](#textmap-propagator) - [Fields](#fields) - [Inject](#inject-1) - [Setter argument](#setter-argument) @@ -49,7 +49,7 @@ and is bound to a data type, in order to propagate in-band context data across p The Propagators API currently defines one `Propagator` type: -- `TextPropagator` is a type that inject values into and extracts values +- `TextMapPropagator` is a type that inject values into and extracts values from carriers as string key/value pairs. A binary `Propagator` type will be added in the future (see [#437](https://github.com/open-telemetry/opentelemetry-specification/issues/437)). @@ -95,9 +95,9 @@ Returns a new `Context` derived from the `Context` passed as argument, containing the extracted value, which can be a `SpanContext`, `CorrelationContext` or another cross-cutting concern context. -## Text Propagator +## TextMap Propagator -`TextPropagator` performs the injection and extraction of a cross-cutting concern +`TextMapPropagator` performs the injection and extraction of a cross-cutting concern value as string key/values pairs into carriers that travel in-band across process boundaries. The carrier of propagated data on both the client (injector) and server (extractor) side is @@ -127,7 +127,7 @@ The use cases of this are: - allow pre-allocation of fields, especially in systems like gRPC Metadata - allow a single-pass over an iterator -Returns list of fields that will be used by the `TextPropagator`. +Returns list of fields that will be used by the `TextMapPropagator`. ### Inject @@ -143,7 +143,7 @@ Optional arguments: Setter is an argument in `Inject` that sets values into given fields. -`Setter` allows a `TextPropagator` to set propagated fields into a carrier. +`Setter` allows a `TextMapPropagator` to set propagated fields into a carrier. One of the ways to implement it is `Setter` class with `Set` method as described below. @@ -175,7 +175,7 @@ Returns a new `Context` derived from the `Context` passed as argument. Getter is an argument in `Extract` that get value from given field -`Getter` allows a `TextPropagator` to read propagated fields from a carrier. +`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. @@ -208,7 +208,7 @@ A composite propagator can be built from a list of propagators, or a list of injectors and extractors. The resulting composite `Propagator` will invoke the `Propagator`s, `Injector`s, or `Extractor`s, in the order they were specified. Each composite `Propagator` will implement a specific `Propagator` type, such -as `TextPropagator`, as different `Propagator` types will likely operate on different +as `TextMapPropagator`, as different `Propagator` types will likely operate on different data types. There MUST be functions to accomplish the following operations. From 144d91b075df4e83662a258268ce001138b06703 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 19 Aug 2020 23:49:25 +0200 Subject: [PATCH 3/6] Update overview.md --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index 3b36f9e1d4d..f4cd0bce1b5 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -285,7 +285,7 @@ imposed by a specific transport and bound to a data type. The Propagators API currently defines one `Propagator` type: -- `TextPropagator` injects values into and extracts values from carriers as text. +- `TextMapPropagator` injects values into and extracts values from carriers as text. ## Collector From 87678716cc9b6011d61ec4ce182ab25e05514cd8 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 20 Aug 2020 14:15:49 +0200 Subject: [PATCH 4/6] Add a small restriction regarding ASCII values. --- specification/context/api-propagators.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 486fe38ec8e..92216d1f718 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -103,6 +103,9 @@ value as string key/values pairs into carriers that travel in-band across proces The carrier of propagated data on both the client (injector) and server (extractor) side is usually an HTTP request. +In order to increase compatibility, the key/value pairs MUST only use US-ASCII octets. +a la [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2.4). + `Getter` and `Setter` are optional helper components used for extraction and injection respectively, and are defined as separate objects from the carrier to avoid runtime allocations, by removing the need for additional interface-implementing-objects wrapping the carrier in order From 19af8829c91194058c42c34732e4b72319406467 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 20 Aug 2020 14:54:39 +0200 Subject: [PATCH 5/6] Update specification/context/api-propagators.md Co-authored-by: Armin Ruech --- specification/context/api-propagators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 92216d1f718..d366ff93df9 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -103,8 +103,8 @@ value as string key/values pairs into carriers that travel in-band across proces The carrier of propagated data on both the client (injector) and server (extractor) side is usually an HTTP request. -In order to increase compatibility, the key/value pairs MUST only use US-ASCII octets. -a la [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2.4). +In order to increase compatibility, the key/value pairs MUST only consist of US-ASCII characters +that make up valid HTTP header fields as per [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2). `Getter` and `Setter` are optional helper components used for extraction and injection respectively, and are defined as separate objects from the carrier to avoid runtime allocations, From ad11666a6620a4c47058953a8d83f2946e1ff5d9 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 21 Aug 2020 16:40:33 +0200 Subject: [PATCH 6/6] Add CHANGELOG entry. --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0014957af6f..5f4d396af81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ Updates: * SpanProcessors must provide read/write access at least in OnStart. - Specify how `Probability` sampler is used with `ParentOrElse` sampler. - Clean up api-propagators.md, by extending documentation and removing redundant sections ([#577](https://github.com/open-telemetry/opentelemetry-specification/pull/577)) +- Rename HTTPText propagator to TextMap ([#793](https://github.com/open-telemetry/opentelemetry-specification/pull/793)) ## v0.6.0 (07-01-2020)