-
Notifications
You must be signed in to change notification settings - Fork 895
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Initial OpenTracing compatibility requirements #768
Changes from 8 commits
1c9bc9d
bcdfb00
3195643
92da36f
dd331ab
b944a2c
c6027ba
272198e
1874ce1
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,148 @@ | ||
# OpenTracing Compatibility | ||
|
||
<details> | ||
<summary>Table of Contents</summary> | ||
|
||
* [Abstract](#abstract) | ||
* [OpenTracing Tracer](#opentracing-tracer) | ||
* [Create a Tracer shim](#create-a-tracer-shim) | ||
* [Inject](#inject) | ||
* [Extract](#extract) | ||
* [ScopeManager](#scopemanager) | ||
* [Activate a Span](#activate-a-span) | ||
* [Get the active Span](#get-the-active-span) | ||
* [Span](#span) | ||
* [Get Context](#get-context) | ||
* [Get Baggage Item](#get-baggage-item) | ||
* [Set Baggage Item](#set-baggage-item) | ||
* [Set Tag](#set-tag) | ||
* [Log](#log) | ||
* [Finish](#finish) | ||
* [SpanContext](#spancontext) | ||
* [Get Baggage Items](#get-baggage-items) | ||
|
||
</details> | ||
|
||
## Abstract | ||
|
||
The OpenTelemetry project aims to provide backwards compatibility with the | ||
[OpenTracing](https://opentracing.io) project in order to ease migration of | ||
instrumented codebases. | ||
|
||
This functionality will be provided as a bridge layer implementing the | ||
[OpenTracing API](https://github.com/opentracing/specification) using the | ||
OpenTelemetry API. This layer MUST NOT rely on implementation specific details | ||
of any SDK. | ||
|
||
## OpenTracing Tracer | ||
|
||
The OpenTracing Tracer operations MUST be implemented using the OpenTelemetry | ||
API: | ||
|
||
- An OpenTelemetry `Tracer` MUST be used to create `Span`s. | ||
- A `CorrelationContextManager` MUST be used to create the `CorrelationContext` | ||
objects used to implement the OpenTracing `Span` baggage. | ||
- A set of `Propagator` MUST be leveraged in order to perform inject and extract operations. | ||
|
||
### Create a Tracer Shim | ||
|
||
The operation MUST accept the following parameters: | ||
|
||
- An OpenTelemetry `Tracer`. | ||
- A `CorrelationContextManager`. | ||
- A set of `Propagator`s of the supported types, usually `Composite Propagator`s. | ||
|
||
The API MUST return an OpenTracing `Tracer`. | ||
|
||
### Inject | ||
|
||
Inject the underlying `SpanContext` using the registered `Propagator`s: | ||
|
||
- `TEXT_MAP` and `HTTP_HEADERS` formats MUST use the registered `HTTPTextPropagator`, if any. | ||
|
||
Errors MUST NOT be raised if the specified OpenTracing `Format` is `BINARY`. | ||
|
||
### Extract | ||
|
||
Extract an OpenTelemetry `SpanContext` from a carrier using the registered `Propagator`s: | ||
|
||
- `TEXT_MAP` and `HTTP_HEADERS` formats MUST use the registered `HTTPTextPropagator`, if any. | ||
|
||
Returns an OpenTracing `SpanContext` with the underlying extracted `SpanContext`, or null if | ||
either the OpenTracing `Format` is `BINARY` or no value could be extracted. | ||
|
||
## ScopeManager. | ||
|
||
For OpenTracing languages implementing the `ScopeManager` interface, its operations | ||
MUST be implemented using the OpenTelemetry context propagation API. | ||
|
||
### Activate a Span. | ||
|
||
Sets the specified `Span` as active for the current `Context`. | ||
|
||
### Get the active Span. | ||
|
||
Gets the active `Span` for the current `Context`. The API MUST return | ||
null if none exist. | ||
|
||
## Span | ||
|
||
The `Span` operations MUST be implemented using an underlying OpenTelemetry `Span` | ||
in conjunction with an associated `CorrelationContext` object used to implement its | ||
baggage part. | ||
|
||
OpenTracing `SpanContext` shim objects MUST act as objects associating an | ||
underlying `SpanContext` with a `CorrelationContext`. Every invocation to the | ||
`Set Baggage Item` operation will result in a newly associated `SpanContext` shim object | ||
with a new `CorrelationContext` containing the specified name/value pair. | ||
|
||
Each underlying `Span` can only be associated with one `SpanContext` shim at a time | ||
for all the execution units. | ||
|
||
The `Log` operations MUST be implemented using `Span`'s `Add Events`. | ||
|
||
The `Set Tag` operations MUST be implemented using `Span`'s `Set Attributes`. | ||
|
||
### Get Context | ||
|
||
Gets the currently associated `SpanContext` shim. | ||
|
||
### Get Baggage Item | ||
|
||
Gets a value for the specified name in the `CorrelationContext` of the associated `SpanContext` | ||
shim or null if none exists. | ||
|
||
### Set Baggage Item | ||
|
||
Creates a newly associated `SpanContext` shim object with a new `CorrelationContext` | ||
containing the specified name/value pair. | ||
|
||
### Set Tag | ||
|
||
Calls `Set Attribute` on the underlying `Span` with the specified name/value pair. | ||
|
||
If the type of the specified value is not supported, the value MUST be converted | ||
to a string. | ||
|
||
### Log | ||
|
||
Calls `Add Event` on the underlying `Span`. | ||
|
||
If an explicit timestamp is specified, a conversion MUST be done to match the OT and | ||
OTel units. | ||
|
||
### Finish | ||
|
||
Calls `End` on the underlying `Span`. | ||
|
||
If an explicit timestamp is specified, a conversion MUST be done to match the OT and | ||
OTel units. | ||
|
||
### SpanContext | ||
|
||
The `SpanContext` interface MUST be implemented using a OpenTelemetry `SpanContext` | ||
in conjunction with an associated `CorrelationContext`. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "must be implemented" is unclear, did you mean "must embed/encapsulate ..."? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please mention how the individual OT SpanContext methods match to the underlying OTel methods. |
||
|
||
#### Get Baggage Items | ||
|
||
Returns a shim exposing the associated `CorrelationContext` values. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am not sure I understand this. Can this even be supported transparently? In OT the SetBaggage is a void function. If it were to be translated into OTel CorrelationContext change, would it not result in the creation of a new instance of the Context object (which may or may not need to be made "current")?