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) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index cc6d0e45429..d366ff93df9 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) +- [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: -- `HTTPTextPropagator` 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,14 +95,17 @@ 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 +## TextMap Propagator -`HTTPTextPropagator` 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 usually an HTTP request. +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, by removing the need for additional interface-implementing-objects wrapping the carrier in order @@ -127,7 +130,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 `TextMapPropagator`. ### Inject @@ -143,7 +146,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 `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 +178,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 `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 +211,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 `TextMapPropagator`, 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 af3ee5d8a68..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: -- `HTTPTextPropagator` injects values into and extracts values from carriers as text. +- `TextMapPropagator` injects values into and extracts values from carriers as text. ## Collector diff --git a/specification/trace/api.md b/specification/trace/api.md index a52997c542d..a2e13eb70e7 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -692,7 +692,7 @@ 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 `TextMapPropagator` implementing the [W3C TraceContext Specification](https://www.w3.org/TR/trace-context/). ## Behavior of the API in the absence of an installed SDK