add SuppressTracing flag

open-telemetry · Jan 13, 2023 · c1c12cd · c1c12cd
1 parent b45fa5e
commit c1c12cd
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 0 deletions.
diff --git 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
@@ -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
@@ -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