diff --git a/CHANGELOG.md b/CHANGELOG.md index a84359118f2..0d41bad083f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ release. ### Context +- Add `SuppressTracing` flag. [](https://github.com/open-telemetry/opentelemetry-specification/pull/) + ### Traces - Clarify that the BatchSpanProcessor should export batches when the queue reaches the batch size diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index c3ff23a5570..7b471f26292 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -28,6 +28,8 @@ formats is required. Implementing more than one format is optional. | [Trace / Context interaction](specification/trace/api.md#context-interaction) | | | | | | | | | | | | | | Get active Span | | N/A | + | + | + | + | + | + | + | + | + | + | | Set active Span | | N/A | + | + | + | + | + | + | + | + | + | + | +| Set SuppressTracing | | | | | | | | | | | | | +| Unset SuppressTracing | | | | | | | | | | | | | | [Tracer](specification/trace/api.md#tracer-operations) | | | | | | | | | | | | | | Create a new Span | | + | + | + | + | + | + | + | + | + | + | + | | Documentation defines adding attributes at span creation as preferred | | | | | + | + | | + | | | + | | diff --git a/specification/trace/api.md b/specification/trace/api.md index d27cbacc9f7..ac16706b780 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -15,6 +15,7 @@ * [TracerProvider operations](#tracerprovider-operations) + [Get a Tracer](#get-a-tracer) - [Context Interaction](#context-interaction) + * [Suppress Tracing](#suppress-tracing) - [Tracer](#tracer) * [Tracer operations](#tracer-operations) - [SpanContext](#spancontext) @@ -169,10 +170,19 @@ instance: - Extract the `Span` from a `Context` instance - Combine the `Span` with a `Context` instance, creating a new `Context` instance +- Set a `SuppressTracing` flag on a `Context` instance +- Get the value of the `SuppressTracing` flag on a `Context`, returning `false` + if undefined +- 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/README.md#create-a-key) used by the Tracing API implementation. +The `SuppressTracing` flag is for 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. + If the language has support for implicitly propagated `Context` (see [here](../context/README.md#optional-global-operations)), the API SHOULD also provide the following functionality: @@ -398,6 +408,10 @@ created in another process. Each propagators' deserialization must set `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the parent is remote. +If the [`SuppressTracing`](#suppress-tracing) `Context` flag is set then the API +MUST return the parent Span marked as non-recording, if one exists, otherwise +return an empty non-recording Span. + Any span that is created MUST also be ended. This is the responsibility of the user. API implementations MAY leak memory or other resources