Skip to content
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

Closed
148 changes: 148 additions & 0 deletions specification/compatibility/opentracing.md
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.
Copy link
Member

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")?


### 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`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"must be implemented" is unclear, did you mean "must embed/encapsulate ..."?

Copy link
Contributor

Choose a reason for hiding this comment

The 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.