Merge branch 'main' into exceptions-on-logs-otep

Author: pellared

CHANGELOG.md

@@ -11,6 +11,8 @@ release.
 
 ### Traces
 
+- Define randomness value requirements for W3C Trace Context Level 2.
+  ([#4162](https://github.com/open-telemetry/opentelemetry-specification/pull/4162))
 - Deprecate `exception.escaped` attribute, add link to in-development semantic-conventions
   on how to record errors across signals.
   ([#4368](https://github.com/open-telemetry/opentelemetry-specification/pull/4368))
@@ -2901,19 +2903,19 @@ Updates:
 
 ## v0.4.0 (2020-05-12)
 
-- [OTEP-83](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md)
+- [OTEP-83](oteps/0083-component.md)
   Introduce the notion of InstrumentationLibrary.
-- [OTEP-88](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0088-metric-instrument-optional-refinements.md)
+- [OTEP-88](oteps/metrics/0088-metric-instrument-optional-refinements.md)
   Metrics API instrument foundation.
-- [OTEP-91](https://github.com/open-telemetry/oteps/blob/main/text/logs/0091-logs-vocabulary.md)
+- [OTEP-91](oteps/logs/0091-logs-vocabulary.md)
   Logs vocabulary.
-- [OTEP-92](https://github.com/open-telemetry/oteps/blob/main/text/logs/0092-logs-vision.md)
+- [OTEP-92](oteps/logs/0092-logs-vision.md)
   Logs Vision.
-- [OTEP-90](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0090-remove-labelset-from-metrics-api.md)
+- [OTEP-90](oteps/metrics/0090-remove-labelset-from-metrics-api.md)
   Remove LabelSet from the metrics API.
-- [OTEP-98](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0098-metric-instruments-explained.md)
+- [OTEP-98](oteps/metrics/0098-metric-instruments-explained.md)
   Explain the metric instruments.
-- [OTEP-99](https://github.com/open-telemetry/oteps/blob/main/text/0099-otlp-http.md)
+- [OTEP-99](oteps/0099-otlp-http.md)
   OTLP/HTTP: HTTP Transport Extension for OTLP.
 - Define handling of null and empty attribute values.
 - Rename Setter.put to Setter.set
@@ -2933,15 +2935,15 @@ Updates:
 
 ## v0.3.0 (2020-02-21)
 
-- [OTEP-0059](https://github.com/open-telemetry/oteps/blob/main/text/trace/0059-otlp-trace-data-format.md)
+- [OTEP-0059](oteps/trace/0059-otlp-trace-data-format.md)
   Add OTLP Trace Data Format specification.
-- [OTEP-0066](https://github.com/open-telemetry/oteps/blob/main/text/0066-separate-context-propagation.md)
+- [OTEP-0066](oteps/0066-separate-context-propagation.md)
   Separate Layer for Context Propagation.
-- [OTEP-0070](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0070-metric-bound-instrument.md)
+- [OTEP-0070](oteps/metrics/0070-metric-bound-instrument.md)
   Rename metric instrument "Handles" to "Bound Instruments".
-- [OTEP-0072](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0072-metric-observer.md)
+- [OTEP-0072](oteps/metrics/0072-metric-observer.md)
   Metric Observer instrument specification (refinement).
-- [OTEP-0080](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0080-remove-metric-gauge.md)
+- [OTEP-0080](oteps/metrics/0080-remove-metric-gauge.md)
   Remove the Metric Gauge instrument, recommend use of other instruments.
 - Update 0003-measure-metric-type to match current Specification.
 - Update 0009-metric-handles to match current Specification.
@@ -2961,23 +2963,23 @@ Updates:
 
 ## v0.2.0 (2019-10-22)
 
-- [OTEP-0001](https://github.com/open-telemetry/oteps/blob/main/text/0001-telemetry-without-manual-instrumentation.md)
+- [OTEP-0001](oteps/0001-telemetry-without-manual-instrumentation.md)
   Added Auto-Instrumentation.
-- [OTEP-0002](https://github.com/open-telemetry/oteps/blob/main/text/trace/0002-remove-spandata.md):
+- [OTEP-0002](oteps/trace/0002-remove-spandata.md):
   Removed SpanData interface in favor of Span Start and End options.
-- [OTEP-0003](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0003-measure-metric-type.md)
+- [OTEP-0003](oteps/metrics/0003-measure-metric-type.md)
   Consolidatesd pre-aggregated and raw metrics APIs.
-- [OTEP-0008](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0008-metric-observer.md)
+- [OTEP-0008](oteps/metrics/0008-metric-observer.md)
   Added Metrics Observers API.
-- [OTEP-0009](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0009-metric-handles.md)
+- [OTEP-0009](oteps/metrics/0009-metric-handles.md)
   Added Metrics Handle API.
-- [OTEP-0010](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0010-cumulative-to-counter.md)
+- [OTEP-0010](oteps/metrics/0010-cumulative-to-counter.md)
   Rename "Cumulative" to "Counter" in the Metrics API.
-- [OTEP-006](https://github.com/open-telemetry/oteps/blob/main/text/trace/0006-sampling.md)
+- [OTEP-006](oteps/trace/0006-sampling.md)
   Moved sampling from the API tp the SDK.
-- [OTEP-0007](https://github.com/open-telemetry/oteps/blob/main/text/0007-no-out-of-band-reporting.md)
+- [OTEP-0007](oteps/0007-no-out-of-band-reporting.md)
   Moved support for out-of-band telemetry from the API to the SDK.
-- [OTEP-0016](https://github.com/open-telemetry/oteps/blob/main/text/0016-named-tracers.md)
+- [OTEP-0016](oteps/0016-named-tracers.md)
   Added named providers for Tracers and Meters.
 - Added design goals and requirements for a telemetry data exchange protocol.
 - Added a Span Processor interface for intercepting span start and end

development/README.md

@@ -14,7 +14,7 @@ Features in Development must be:
 To avoid any confusion, all files in this directory must have a note about its Development status.
 
 Development status precedes the alpha version (see
-[OTEP 0232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#explanation)).
+[OTEP 0232](../oteps/0232-maturity-of-otel.md#explanation)).
 All changes in the `development` folder go through the regular review process. Changes are allowed to be merged faster as completeness of a solution is not a requirement. Approval means that proposed changes are OK for experimentation.
 
 When the feature or parts of it are developed far enough to declare them as an alpha version of a main project and move out of the Development status, it must go through a **new** OTEP PR and it must be expected that design and APIs will be changed. In fact, the same people who approved the experiment may likely be the most critical reviewers. It demonstrates an interest and involvement, not critique.

development/trace/zpages.md

@@ -24,7 +24,7 @@
 
 zPages are an in-process alternative to external exporters. When included, they collect and aggregate tracing and metrics information in the background; this data is served on web pages when requested.
 
-The idea of "zPages" originates from one of OpenTelemetry's predecessors, [OpenCensus](https://opencensus.io/). You can read more about zPages from the OpenCensus docs [here](https://opencensus.io/zpages) or the OTEP [here](https://github.com/open-telemetry/oteps/blob/main/text/0110-z-pages.md). OpenCensus has different zPage implementations in [Java](https://opencensus.io/zpages/java/), [Go](https://opencensus.io/zpages/go/), and [Node](https://opencensus.io/zpages/node/) and there has been similar internal solutions developed at companies like Uber. Within OpenTelemetry, zPages are available in Go and Rust. The OTel Collector also has [an implementation](https://github.com/open-telemetry/opentelemetry-collector/tree/master/extension/zpagesextension) of zPages.
+The idea of "zPages" originates from one of OpenTelemetry's predecessors, [OpenCensus](https://opencensus.io/). You can read more about zPages from the OpenCensus docs [here](https://opencensus.io/zpages) or the OTEP [here](../../oteps/0110-z-pages.md). OpenCensus has different zPage implementations in [Java](https://opencensus.io/zpages/java/), [Go](https://opencensus.io/zpages/go/), and [Node](https://opencensus.io/zpages/node/) and there has been similar internal solutions developed at companies like Uber. Within OpenTelemetry, zPages are available in Go and Rust. The OTel Collector also has [an implementation](https://github.com/open-telemetry/opentelemetry-collector/tree/master/extension/zpagesextension) of zPages.
 
 zPages are uniquely useful in a couple of different ways. One is that they're more lightweight and quicker compared to installing external tracing systems like Jaeger and Zipkin, yet they still share useful ways to debug and gain insight into instrumented applications; these uses depend on the type of zPage, which is detailed below. For high throughput applications, zPages can also analyze more telemetry with the limited set of supported scenarios than external exporters; this is because zPages are in-memory while external exporters are typically configured to send a subset of telemetry for reach analysis to save costs.
 

oteps/0156-columnar-encoding.md

@@ -7,7 +7,7 @@
 **Abstract**: This OTEP describes a new protocol, the OTelArrow protocol, which is based on a **generic columnar representation
 for metrics, logs and traces**.  This protocol significantly improves efficiency in scenarios involving the transmission
 of large batches of metrics, logs, traces. Moreover, it provides a better representation for [multivariate time-series](#multivariate-time-series).
-The OTelArrow protocol also supports a fallback mechanism to the [OpenTelemetry protocol (OTEP 0035)](https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md)
+The OTelArrow protocol also supports a fallback mechanism to the [OpenTelemetry protocol (OTEP 0035)](0035-opentelemetry-protocol.md)
 in instances when one of the endpoints does not support the OTelArrow protocol.
 
 **Reference implementation**: The [OTel Arrow Adapter](https://github.com/f5/otel-arrow-adapter) Go library specifies
@@ -70,7 +70,7 @@ other in memory. The main benefits of a columnar approach are:
 
 ![row vs column-oriented](img/0156_OTEL%20-%20Row%20vs%20Column.png)
 
-This OTEP proposes to improve the [OpenTelemetry protocol (OTEP 0035)](https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md)
+This OTEP proposes to improve the [OpenTelemetry protocol (OTEP 0035)](0035-opentelemetry-protocol.md)
 with a **generic columnar representation for metrics, logs and traces based on Apache Arrow**. Compared to the existing
 OpenTelemetry protocol this compatible extension has the following improvements:
 
@@ -85,7 +85,7 @@ OpenTelemetry protocol this compatible extension has the following improvements:
   efficiency, and data minimization require additional data processing capabilities such as data projection,
   aggregation, and filtering.
 
-These improvements not only address the aforementioned needs but also answer the [open questions](https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md#open-questions)
+These improvements not only address the aforementioned needs but also answer the [open questions](0035-opentelemetry-protocol.md#open-questions)
 cited in OTEP 035 (i.e. cpu usage, memory pressure, compression optimization).
 
 **It is important to understand that this proposal is complementary to the existing protocol. The row-oriented version
@@ -749,7 +749,7 @@ the client select between OTLP or OTel Arrow protocol depending on the nature of
 ## Future Versions and Interoperability
 
 As far as protocol evolution and interoperability mechanisms are concerned, this extension follows the
-[recommendations](https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md#future-versions-and-interoperability)
+[recommendations](0035-opentelemetry-protocol.md#future-versions-and-interoperability)
 outlined in the OTLP spec.
 
 ## Prior Art and Alternatives

oteps/0243-app-telemetry-schema-vision-roadmap.md

@@ -7,7 +7,7 @@
 Discoverability, Interoperability, Type-Safe Client SDKs, Client SDKs Generation,
 CI/CD Integration, Data Governance, Data Privacy.
 
-**Related OTEPs**: [OTEP0152](https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md), [OTEP0202](https://github.com/open-telemetry/oteps/blob/main/text/0202-events-and-logs-api.md).
+**Related OTEPs**: [OTEP0152](0152-telemetry-schemas.md), [OTEP0202](0202-events-and-logs-api.md).
 
 ----
 _Unlike the traditional data ecosystem (OLTP and OLAP), the world of telemetry
@@ -193,7 +193,7 @@ Telemetry Schemas would replace/augment existing SchemaURL.
 ![Use cases](./img/0243-otel-weaver-use-cases.svg)
 
 Note: The relationship between Telemetry Schema v1.1
-([OTEP 0152](https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md))
+([OTEP 0152](0152-telemetry-schemas.md))
 and the Component and Resolved Telemetry Schema concepts is still being
 discussed. This will be clarified in future OTEPs (refer to the last section).
 

oteps/entities/0264-resource-and-entities.md

@@ -214,7 +214,7 @@ The DataModel would ensure that attributes in Resource are produced from both th
 
 ### ResourceEntityRef
 
-The entityref data model, would have the following changes from the original [entity OTEP](https://github.com/open-telemetry/oteps/blob/main/text/entities/0256-entities-data-model.md) to denote references within Resource:
+The entityref data model, would have the following changes from the original [entity OTEP](0256-entities-data-model.md) to denote references within Resource:
 
 | Field | Type | Description | Changes |
 | ----- | ---- | ----------- | ------- |

oteps/trace/0168-sampling-propagation.md

@@ -441,11 +441,11 @@ data to avoid the computational cost of hashing TraceIDs.
 
 Restricting parent sampling probabilities to powers of two does not limit tail
 Samplers from using arbitrary probabilities.  The companion [OTEP
-170](https://github.com/open-telemetry/oteps/blob/main/text/trace/0170-sampling-probability.md) has discussed
+170](0170-sampling-probability.md) has discussed
 the use of a `sampler.adjusted_count` attribute that would not be
 limited to power-of-two values.  Discussion about how to represent the
 effective adjusted count for tail-sampled Spans belongs in [OTEP
-170](https://github.com/open-telemetry/oteps/blob/main/text/trace/0170-sampling-probability.md), not this OTEP.
+170](0170-sampling-probability.md), not this OTEP.
 
 Restricting parent sampling probabilities to powers of two does not limit
 Samplers from using arbitrary effective probabilities over a period of
@@ -465,7 +465,7 @@ propagate the `p` value when the context is not sampled, since
 `ParentBased` samplers will not change the decision.  Although one
 use-case was docmented in Google's early Dapper system (known as
 "inflationary sampling", see
-[OTEP 170](https://github.com/open-telemetry/oteps/blob/main/text/trace/0170-sampling-probability.md#dappers-inflationary-sampler)), the same effect can
+[OTEP 170](0170-sampling-probability.md#dappers-inflationary-sampler)), the same effect can
 be achieved using a consistent sampling decision in this framework.
 
 ### Default behavior

oteps/trace/0220-messaging-semantic-conventions-span-structure.md

@@ -61,7 +61,7 @@ scenarios and different messaging systems.
 
 ## Stages of producing and consuming messages
 
-As previously described in [OTEP 173](https://github.com/open-telemetry/oteps/blob/main/text/trace/0173-messaging-semantic-conventions.md#scenarios.),
+As previously described in [OTEP 173](0173-messaging-semantic-conventions.md#scenarios),
 producing and consuming a message involves five stages:
 
 ```mermaid

spec-compliance-matrix.md

@@ -87,6 +87,7 @@ formats is required. Implementing more than one format is optional.
 | [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) |          |     | +    |     | +      | +    | +      | +   | +    | +   | +    |       |
 | [Attribute Limits](specification/common/README.md#attribute-limits)                              | X        |     | +    |     | +      | +    | +      | +   |      |     |      |       |
 | Fetch InstrumentationScope from ReadableSpan                                                     |          |     | +    |     | +      |      |        | +   |      |     |      |       |
+| [Support W3C Trace Context Level 2 randomness](specification/trace/sdk.md#traceid-randomness)                            | X        |     |      |     |        |      |        |     |      |     |      |       |
 
 ## Baggage
 
@@ -180,9 +181,9 @@ formats is required. Implementing more than one format is optional.
 | A metric Producer accepts an optional metric Filter                                                                                                                    |          |    |      |     |        |      | -      |     |      |     |      |       |
 | The metric Reader implementation supports registering metric Filter and passing them  its registered metric Producers                                                  |          |    |      |     |        |      | -      |     |      |     |      |       |
 | The metric SDK's metric Producer implementations uses the metric Filter                                                                                                |          |    |      |     |        |      | -      |     |      |     |      |       |
-| Metric SDK implements [cardinality limit](./specification/metrics/sdk.md#cardinality-limits)                                                                           |          |    |      |     |        |      |        |     |      |     |      |       |
-| Metric SDK supports configuring cardinality limit at MeterReader level                                                                                                 |          |    |      |     |        |      |        |     |      |     |      |       |
-| Metric SDK supports configuring cardinality limit per metric (using Views)                                                                                             |          |    |      |     |        |      |        |     |      |     |      |       |
+| Metric SDK implements [cardinality limit](./specification/metrics/sdk.md#cardinality-limits)                                                                           |          |    |  +   |  +   |   -    |     |        |     |  -   |  +  |   +   |       |
+| Metric SDK supports configuring cardinality limit at MeterReader level                                                                                                 |          |    |  +   |  +   |   -    |     |        |     |  -   |  -  |   -   |       |
+| Metric SDK supports configuring cardinality limit per metric (using Views)                                                                                             |          |    |  +   |  +   |   -    |     |        |     |  -   |  -  |   +   |       |
 
 ## Logs
 

specification/context/api-propagators.md

@@ -32,6 +32,7 @@
   * [Get Global Propagator](#get-global-propagator)
   * [Set Global Propagator](#set-global-propagator)
 - [Propagators Distribution](#propagators-distribution)
+  * [W3C Trace Context Requirements](#w3c-trace-context-requirements)
   * [B3 Requirements](#b3-requirements)
     + [B3 Extract](#b3-extract)
     + [B3 Inject](#b3-inject)
@@ -377,6 +378,17 @@ Additional `Propagator`s implementing vendor-specific protocols such as AWS
 X-Ray trace header protocol MUST NOT be maintained or distributed as part of
 the Core OpenTelemetry repositories.
 
+### W3C Trace Context Requirements
+
+A W3C Trace Context propagator MUST parse and validate the `traceparent` and `tracestate` HTTP headers as specified in [W3C Trace Context Level 2](https://www.w3.org/TR/trace-context-2/).  A W3C Trace Context propagator MUST propagate a valid `traceparent` value using the same header.  A W3C Trace Context propagator MUST propagate a valid `tracestate` unless the value is empty, in which case the `tracestate` header may be omitted.
+
+When injecting and extracting trace context to or from a carrier, the following fields from the `SpanContext` are propagated.
+
+- TraceID (16 bytes)
+- SpanID (8 bytes)
+- TraceFlags (8 bits)
+- TraceState (string, unless empty)
+
 ### B3 Requirements
 
 B3 has both single and multi-header encodings. It also has semantics that do not