Add Correlations API #101
Merged
Add Correlations API #101
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This provides an implementation of the [Context API Spec](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/context.md). A context is a propagation mechanism which carries execution-scoped values across API boundaries and between logically associated execution units. Cross-cutting concerns access their data in-process using the same shared `Context` object. It is implemented as an immutable thread-local collection of heterogeneous values that can be inserted and retrieved by their type. A thread's current context can be assigned via the `attach` method. The previous context is restored as the current context when the resulting context guard is dropped, allowing precise control and nesting of active context scopes.
This change moves the storage and management of active spans from the
current `SpanStack` implementation to the new `Context` api, as well as
updating the propagation APIs to inject and extract contexts to remain
compatible with the tracers. This has some breaking API changes to the
way tracing is currently done, most notable is that the `Tracer`'s
`start` method no longer requires an optional parent span context as
that can now be provided by the current context.
The previous tracing api was:
```rust
// extract
let remote_span_context = propagator.extract(&carrier);
// start
let parent = tracer.start("parent", Some(remote_context));
tracer.mark_span_as_active(&parent);
// nest (note: `Some(parent.get_context())` and `None` had the same effect here)
let child = tracer.start("child", None);
tracer.mark_span_as_active(&child)
// inject
propagator.inject(child.get_context(), &mut carrier);
// Marking as inactive was required and error-prone
trace.mark_span_as_inactive(&child);
trace.mark_span_as_inactive(&parent);
```
And the new API is:
```rust
// extract
let _attach = propagator.extract(&carrier).attach();
// start
let parent = tracer.start("parent");
let _parent_active = tracer.mark_span_as_active(parent);
// start
let child = tracer.start("child");
let _child_active = tracer.mark_span_as_active(parent);
// inject
propagator.inject(&mut carrier)
```
Additional changes to facilitate the switch:
* `tracer.with_span` now accepts a span for naming consistency and
managing the active state of a more complex span (likely produced by a
builder), and the previous functionality that accepts a `&str` has been
renamed to `in_span`, both of which now yield a context to the provided
closure.
* The `Instrument` trait has been renamed to `FutureExt` to avoid
clashing with metric instruments, and accepts contexts.
* `TracerGenerics` methods have been folded in to the `Tracer` trait so
the trait is no longer needed 🎉 .
* A `TraceContextExt` trait provides methods for working with trace data
in a context. Most notably `context.span()` returns a `&dyn api::Span`
reference, and `Context::current_with_span(span)` creates a clone of the
current context with the span added.
* Span's managing their own active state is no longer needed 🎉.
* Span's `get_context` method has been renamed to `span_context` to
avoid the ambiguity.
This adds an implementation of the [Correlations API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/correlationcontext/api.md) which is used to annotate telemetry, adding context and information to metrics, traces, and logs. It is an abstract data type represented by a set of name/value pairs describing user-defined properties. Example: ```rust let propagator = CorrelationContextPropagator::new(); // can extract from any type that impls `Carrier`, usually an HTTP header map let cx = propagator.extract(&headers); // Iterate over extracted name / value pairs for (name, value) in cx.correlation_context() { // ... } // Add new correlations let cx_with_additions = cx.with_correlations(vec![Key::new("server_id").u64(42)]); // Inject correlations into http request propagator.inject_context(&cx_with_additions, &mut headers); ``` Resolves #62
MikeGoldsmith
approved these changes
May 6, 2020
cijothomas
pushed a commit
to cijothomas/opentelemetry-rust
that referenced
this pull request
Sep 7, 2024
Co-authored-by: Lalit Kumar Bhasin <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds an implementation of the Correlations API which is used to annotate telemetry, adding context and information to metrics, traces, and logs. It is an abstract data type represented by a set of name/value pairs describing user-defined properties.
Example:
Resolves #62