diff --git a/CHANGELOG.md b/CHANGELOG.md index 62ad051feef..fc81c8af4b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ release. - Added `OTEL_EXPORTER_JAEGER_TIMEOUT` environment variable. ([#1612](https://github.com/open-telemetry/opentelemetry-specification/pull/1612)) - Added `OTEL_EXPORTER_ZIPKIN_TIMEOUT` environment variable. ([#1636](https://github.com/open-telemetry/opentelemetry-specification/pull/1636)) +- Added Suppress Tracing context key. ([#1653](https://github.com/open-telemetry/opentelemetry-specification/pull/1653)) ### Traces diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index ee90e5ef2aa..02e7b21c823 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -51,6 +51,7 @@ formats is required. Implementing more than one format is optional. | events collection size limit | | + | + | + | + | + | - | | + | + | - | + | | attribute collection size limit | | + | + | + | + | + | - | | + | + | - | + | | links collection size limit | | + | + | + | + | + | - | | + | + | - | + | +| `SuppressTracing` context flag | | | | | | | | | | | | | | [Span attributes](specification/trace/api.md#set-attributes) | | | | | | | | | | | | | | SetAttribute | | + | + | + | + | + | + | + | + | + | + | + | | Set order preserved | X | + | - | + | + | + | + | + | + | + | + | + | diff --git a/specification/trace/api.md b/specification/trace/api.md index 942f808956f..33a4a5eb781 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -14,6 +14,7 @@ Table of Contents * [TracerProvider](#tracerprovider) * [TracerProvider operations](#tracerprovider-operations) * [Context Interaction](#context-interaction) + * [Suppress Tracing](#suppress-tracing) * [Tracer](#tracer) * [Tracer operations](#tracer-operations) * [SpanContext](#spancontext) @@ -145,6 +146,8 @@ instance: - Extract the `Span` from a `Context` instance - Insert the `Span` to a `Context` instance +- Set a `SuppressTracing` flag on a `Context` instance +- Unset the `SuppressTracing` flag on a `Context` instance The functionality listed above is necessary because API users SHOULD NOT have access to the [Context Key](../context/context.md#create-a-key) used by the Tracing API implementation. @@ -160,6 +163,14 @@ All the above functionalities operate solely on the context API, and they MAY be exposed as either static methods on the trace module, or as static methods on a class inside the trace module. This functionality SHOULD be fully implemented in the API when possible. +### Suppress Tracing + +In some cases it may be useful to temporarily suppress tracing. +For example, this may be used to prevent span exports from being traced and exported, +or by an instrumentation which wraps a lower-level package which may also be +instrumented in order to prevent duplicate spans. To see how tracing is suppressed, +see [SDK Span creation](./sdk.md#sdk-span-creation). + ## Tracer The tracer is responsible for creating `Span`s. @@ -344,6 +355,9 @@ The API MUST accept the following parameters: The semantic parent of the Span MUST be determined according to the rules described in [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context). + + If the `Context` key described in [Suppress Tracing](#suppress-tracing) is set to true, + the newly created `Span` should be a non-recording `Span` with an invalid `SpanContext`. - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified. - [`Attributes`](../common/common.md#attributes). Additionally, these attributes may be used to make a sampling decision as noted in [sampling diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index e09f44b51c4..56ddbbfd3f3 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -183,6 +183,8 @@ When asked to create a Span, the SDK MUST act as if doing the following in order A non-recording span MAY be implemented using the same mechanism as when a `Span` is created without an SDK installed or as described in [wrapping a SpanContext in a Span](api.md#wrapping-a-spancontext-in-a-span). + If the [`SuppressTracing`](./api.md#suppress-tracing) `Context` flag is set, + the newly created `Span` should be a non-recording `Span`. ### Sampler