Merge remote-tracking branch 'origin/master' into provider-rename

specification/api-propagators.md

@@ -5,6 +5,7 @@
 Table of Contents
 </summary>
 
+- [Overview](#overview)
 - [HTTP Text Format](#http-text-format)
   - [Fields](#fields)
   - [Inject](#inject)
@@ -13,22 +14,34 @@ Table of Contents
   - [Extract](#extract)
     - [Getter argument](#getter)
       - [Get](#get)
+- [Composite Propagator](#composite-propagator)
+- [Global Propagators](#global-propagators)
 
 </details>
 
-Propagators API currently consists of one format:
+## Overview
+
+Cross-cutting concerns send their state to the next process using
+`Propagator`s, which are defined as objects used to read and write
+context data to and from messages exchanged by the applications.
+Each concern creates a set of `Propagator`s for every supported `Format`.
+
+The Propagators API is expected to be leveraged by users writing
+instrumentation libraries.
+
+Propagators API currently consists of one `Format`:
 
 - `HTTPTextFormat` is used to inject and extract a value as text into carriers that travel
   in-band across process boundaries.
 
 Deserializing must set `IsRemote` to true on the returned `SpanContext`.
 
-A binary format will be added in the future.
+A binary `Format` will be added in the future.
 
 ## HTTP Text Format
 
-`HTTPTextFormat` is a formatter that injects and extracts a value as text into carriers that
-travel in-band across process boundaries.
+`HTTPTextFormat` is a formatter that injects and extracts a cross-cutting concern
+value as text into carriers that travel in-band across process boundaries.
 
 Encoding is expected to conform to the HTTP Header Field semantics. Values are often encoded as
 RPC/HTTP request headers.
@@ -62,7 +75,7 @@ Injects the value downstream. For example, as http headers.
 
 Required arguments:
 
-- the value to be injected, can be `SpanContext` or `DistributedContext`.
+- the cross-cutting concern value to be injected, such as `SpanContext` or `DistributedContext`.
 - the carrier that holds propagation fields. For example, an outgoing message or http request.
 - the `Setter` invoked for each propagation key to add or remove.
 
@@ -99,7 +112,7 @@ Required arguments:
 - the carrier holds propagation fields. For example, an outgoing message or http request.
 - the instance of `Getter` invoked for each propagation key to get.
 
-Returns the non-null extracted value.
+Returns the non-null cross-cutting concern extracted value.
 
 #### Getter argument
 
@@ -118,4 +131,72 @@ Required arguments:
 - the carrier of propagation fields, such as an HTTP request.
 - the key of the field.
 
-The Get function is responsible for handling case sensitivity. If the getter is intended to work with a HTTP request object, the getter MUST be case insensitive. To improve compatibility with other text-based protocols, text format implemenations MUST ensure to always use the canonical casing for their attributes. NOTE: Cannonical casing for HTTP headers is usually title case (e.g. `Content-Type` instead of `content-type`).
+The Get function is responsible for handling case sensitivity. If the getter is intended to work with a HTTP request object, the getter MUST be case insensitive. To improve compatibility with other text-based protocols, text `Format` implementions MUST ensure to always use the canonical casing for their attributes. NOTE: Cannonical casing for HTTP headers is usually title case (e.g. `Content-Type` instead of `content-type`).
+
+## Composite Propagator
+
+Implementations MUST offer a facility to group multiple `Propagator`s
+from different cross-cutting concerns in order to leverage them as a
+single entity.
+
+The resulting composite `Propagator` will invoke the `Propagators`
+in the order they were specified.
+
+Each composite `Propagator` will be bound to a specific `Format`, such
+as `HttpTextFormat`, as different `Format`s will likely operate on different
+data types.
+There MUST be functions to accomplish the following operations.
+
+- Create a composite propagator
+- Extract from a composite propagator
+- Inject into a composite propagator
+
+### Create a Composite Propagator
+
+Required arguments:
+
+- A list of `Propagator`s.
+
+Returns a new composite `Propagator` with the specified `Propagator`s.
+
+### Extract
+
+Required arguments:
+
+- A `Context`.
+- The carrier that holds propagation fields.
+- The instance of `Getter` invoked for each propagation key to get.
+
+### Inject
+
+Required arguments:
+
+- A `Context`.
+- The carrier that holds propagation fields.
+- The `Setter` invoked for each propagation key to add or remove.
+
+## Global Propagators
+
+Implementations MAY provide global `Propagator`s for
+each supported `Format`.
+
+If offered, the global `Propagator`s should default to a composite `Propagator`
+containing W3C Trace Context and Correlation Context `Propagator`s,
+in order to provide propagation even in the presence of no-op
+OpenTelemetry implementations.
+
+### Get Global Propagator
+
+This method MUST exist for each supported `Format`.
+
+Returns a global `Propagator`. This usually will be composite instance.
+
+### Set Global Propagator
+
+This method MUST exist for each supported `Format`.
+
+Sets the global `Propagator` instance.
+
+Required parameters:
+
+- A `Propagator`. This usually will be a composite instance.

specification/api-tracing.md

@@ -12,10 +12,6 @@ Table of Contents
 * [Tracer](#tracer)
   * [Obtaining a tracer](#obtaining-a-tracer)
   * [Tracer operations](#tracer-operations)
-    * [GetCurrentSpan](#getcurrentspan)
-    * [WithSpan](#withspan)
-    * [SpanBuilder](#spanbuilder)
-    * [GetHttpTextFormat](#gethttptextformat)
 * [SpanContext](#spancontext)
 * [Span](#span)
   * [Span creation](#span-creation)
@@ -76,14 +72,14 @@ The OpenTelemetry library achieves in-process context propagation of `Span`s by
 way of the `Tracer`.
 
 The `Tracer` is responsible for tracking the currently active `Span`, and
-exposes methods for creating and activating new `Span`s. The `Tracer` is
+exposes functions for creating and activating new `Span`s. The `Tracer` is
 configured with `Propagator`s which support transferring span context across
 process boundaries.
 
 ### Obtaining a Tracer
 
 New `Tracer` instances can be created via a `TracerProvider` and its `getTracer`
-method. This method expects two string arguments:
+function. This function expects two string arguments:
 
 `TracerProvider`s are generally expected to be used as singletons. Implementations
 SHOULD provide a single global default `TracerProvider`.
@@ -124,7 +120,7 @@ mechanism, for instance the `ServiceLoader` class in Java.
 
 ### Tracer operations
 
-The `Tracer` MUST provide methods to:
+The `Tracer` MUST provide functions to:
 
 - Get the currently active `Span`
 - Create a new `Span`
@@ -144,7 +140,7 @@ explicit parent is provided or the option to create a span without a parent is
 selected, or the current active `Span` is invalid.
 
 The `Tracer` MUST provide a way to update its active `Span`, and MAY provide
-convenience methods to manage a `Span`'s lifetime and the scope in which a
+convenience functions to manage a `Span`'s lifetime and the scope in which a
 `Span` is active. When an active `Span` is made inactive, the previously-active
 `Span` SHOULD be made active. A `Span` maybe finished (i.e. have a non-null end
 time) but stil active. A `Span` may be active on one thread after it has been
@@ -335,7 +331,7 @@ Links SHOULD preserve the order in which they're set.
 
 ### Span operations
 
-With the exception of the method to retrieve the `Span`'s `SpanContext` and
+With the exception of the function to retrieve the `Span`'s `SpanContext` and
 recording status, none of the below may be called after the `Span` is finished.
 
 #### Get Context
@@ -450,10 +446,10 @@ It is highly discouraged to update the name of a `Span` after its creation.
 spans. And often, filtering logic will be implemented before the `Span` creation
 for performance reasons. Thus the name update may interfere with this logic.
 
-The method name is called `UpdateName` to differentiate this method from the
-regular property setter. It emphasizes that this operation signifies a
-major change for a `Span` and may lead to re-calculation of sampling or
-filtering decisions made previously depending on the implementation.
+The function name is called `UpdateName` to differentiate this function from the
+regular property setter. It emphasizes that this operation signifies a major
+change for a `Span` and may lead to re-calculation of sampling or filtering
+decisions made previously depending on the implementation.
 
 Alternatives for the name update may be late `Span` creation, when Span is
 started with the explicit timestamp from the past at the moment where the final

specification/data-database.md

@@ -13,7 +13,6 @@ attribute names.
 
 | Attribute name | Notes and examples                                           | Required? |
 | :------------- | :----------------------------------------------------------- | --------- |
-| `component`    | Database driver name or database name (when known) `"JDBI"`, `"jdbc"`, `"odbc"`, `"postgreSQL"`. | Yes       |
 | `db.type`      | Database type. For any SQL database, `"sql"`. For others, the lower-case database category, e.g. `"cassandra"`, `"hbase"`, or `"redis"`. | Yes       |
 | `db.instance`  | Database instance name. E.g., In java, if the jdbc.url=`"jdbc:mysql://db.example.com:3306/customers"`, the instance name is `"customers"`. | Yes       |
 | `db.statement` | A database statement for the given database type. Note, that the value may be sanitized to exclude sensitive information. E.g., for `db.type="sql"`, `"SELECT * FROM wuser_table"`; for `db.type="redis"`, `"SET mykey 'WuValue'"`. | Yes       |

specification/data-http.md

@@ -70,7 +70,6 @@ Note that the items marked with [1] are different from the mapping defined in th
 
 | Attribute name | Notes and examples                                           | Required? |
 | :------------- | :----------------------------------------------------------- | --------- |
-| `component`    | Denotes the type of the span and needs to be `"http"`. | Yes |
 | `http.method` | HTTP request method. E.g. `"GET"`. | Yes |
 | `http.url` | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | Defined later. |
 | `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. |
@@ -216,7 +215,6 @@ Span name: `/webshop/articles/4` (NOTE: This is subject to change, see [open-tel
 
 |   Attribute name   |                                       Value             |
 | :----------------- | :-------------------------------------------------------|
-| `component`        | `"http"`                                                |
 | `http.method`      | `"GET"`                                                 |
 | `http.flavor`      | `"1.1"`                                                 |
 | `http.url`         | `"https://example.com:8080/webshop/articles/4?s=1"`     |
@@ -230,7 +228,6 @@ Span name: `/webshop/articles/:article_id`.
 
 |   Attribute name   |                      Value                      |
 | :----------------- | :---------------------------------------------- |
-| `component`        | `"http"`                                        |
 | `http.method`      | `"GET"`                                         |
 | `http.flavor`      | `"1.1"`                                         |
 | `http.target`      | `"/webshop/articles/4?s=1"`                     |

specification/data-rpc.md

@@ -32,7 +32,6 @@ Examples of span name: `grpc.test.EchoService/Echo`.
 
 | Attribute name | Notes and examples                                           | Required? |
 | -------------- | ------------------------------------------------------------ | --------- |
-| `component`    | Declares that this is a grpc component. Value MUST be `"grpc"`. | Yes       |
 | `rpc.service`  | The service name, must be equal to the $service part in the span name. | Yes |
 | `net.peer.ip`  | See [network attributes][]. | See below |
 | `net.peer.name`  | See [network attributes][]. | See below |

specification/overview.md

@@ -94,7 +94,7 @@ A **Span** may be linked to zero or more other **Spans** (defined by
 **SpanContext**) that are causally related. **Links** can point to
 **SpanContexts** inside a single **Trace** or across different **Traces**.
 **Links** can be used to represent batched operations where a **Span** was
-initiated by multiple initiating **Span**s, each representing a single incoming
+initiated by multiple initiating **Spans**, each representing a single incoming
 item being processed in the batch.
 
 Another example of using a **Link** is to declare the relationship between
@@ -107,7 +107,7 @@ initiated by one of many fast incoming requests.
 When using the scatter/gather (also called fork/join) pattern, the root
 operation starts multiple downstream processing operations and all of them are
 aggregated back in a single **Span**. This last **Span** is linked to many
-operations it aggregates. All of them are the **Span**s from the same Trace. And
+operations it aggregates. All of them are the **Spans** from the same Trace. And
 similar to the Parent field of a **Span**. It is recommended, however, to not
 set parent of the **Span** in this scenario as semantically the parent field
 represents a single parent scenario, in many cases the parent **Span** fully
@@ -237,8 +237,9 @@ for an example.
 
 ## Propagators
 
-OpenTelemetry uses `Propagators` to serialize and deserialize `SpanContext` and `DistributedContext`
-into text format. Currently there is one type of propagator:
+OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values
+such as  `SpanContext` and `DistributedContext` into a `Format`. Currently there is one
+type of propagator:
 
 - `HTTPTextFormat` which is used to inject and extract a value as text into carriers that travel
   in-band across process boundaries.