| 1 |
// Copyright The OpenTelemetry Authors |
| 2 |
// SPDX-License-Identifier: Apache-2.0 |
| 3 |
|
| 4 |
// Package opentracing implements a bridge that forwards OpenTracing API |
| 5 |
// calls to the OpenTelemetry SDK. |
| 6 |
// |
| 7 |
// To use the bridge, first create an OpenTelemetry tracer of |
| 8 |
// choice. Then use the NewTracerPair() function to create two tracers |
| 9 |
// - one implementing OpenTracing API (BridgeTracer) and one that |
| 10 |
// implements the OpenTelemetry API (WrapperTracer) and mostly |
| 11 |
// forwards the calls to the OpenTelemetry tracer of choice, but does |
| 12 |
// some extra steps to make the interaction between both APIs |
| 13 |
// working. If the OpenTelemetry tracer of choice already knows how to |
| 14 |
// cooperate with OpenTracing API through the OpenTracing bridge |
| 15 |
// (explained in detail below), then it is fine to skip the |
| 16 |
// WrapperTracer by calling the NewBridgeTracer() function to get the |
| 17 |
// bridge tracer and then passing the chosen OpenTelemetry tracer to |
| 18 |
// the SetOpenTelemetryTracer() function of the bridge tracer. |
| 19 |
// |
| 20 |
// To use an OpenTelemetry span as the parent of an OpenTracing span, |
| 21 |
// create a context using the ContextWithBridgeSpan() function of |
| 22 |
// the bridge tracer, and then use the StartSpanFromContext function |
| 23 |
// of the OpenTracing API. |
| 24 |
// |
| 25 |
// Bridge tracer also allows the user to install a warning handler |
| 26 |
// through the SetWarningHandler() function. The warning handler will |
| 27 |
// be called when there is some misbehavior of the OpenTelemetry |
| 28 |
// tracer with regard to the cooperation with the OpenTracing API. |
| 29 |
// |
| 30 |
// For an OpenTelemetry tracer to cooperate with OpenTracing API |
| 31 |
// through the BridgeTracer, the OpenTelemetry tracer needs to |
| 32 |
// (reasoning is below the list): |
| 33 |
// |
| 34 |
// 1. Return the same context it received in the Start() function if |
| 35 |
// migration.SkipContextSetup() returns true. |
| 36 |
// |
| 37 |
// 2. Implement the migration.DeferredContextSetupTracerExtension |
| 38 |
// interface. The implementation should setup the context it would |
| 39 |
// normally do in the Start() function if the |
| 40 |
// migration.SkipContextSetup() function returned false. Calling |
| 41 |
// ContextWithBridgeSpan() is not necessary. |
| 42 |
// |
| 43 |
// 3. Have an access to the BridgeTracer instance. |
| 44 |
// |
| 45 |
// 4. If the migration.SkipContextSetup() function returned false, the |
| 46 |
// tracer should use the ContextWithBridgeSpan() function to install the |
| 47 |
// created span as an active OpenTracing span. |
| 48 |
// |
| 49 |
// There are some differences between OpenTracing and OpenTelemetry |
| 50 |
// APIs, especially with regard to Go context handling. When a span is |
| 51 |
// created with an OpenTracing API (through the StartSpan() function) |
| 52 |
// the Go context is not available. BridgeTracer has access to the |
| 53 |
// OpenTelemetry tracer of choice, so in the StartSpan() function |
| 54 |
// BridgeTracer translates the parameters to the OpenTelemetry version |
| 55 |
// and uses the OpenTelemetry tracer's Start() function to actually |
| 56 |
// create a span. The OpenTelemetry Start() function takes the Go |
| 57 |
// context as a parameter, so BridgeTracer at this point passes a |
| 58 |
// temporary context to Start(). All the changes to the temporary |
| 59 |
// context will be lost at the end of the StartSpan() function, so the |
| 60 |
// OpenTelemetry tracer of choice should not do anything with the |
| 61 |
// context. If the returned context is different, BridgeTracer will |
| 62 |
// warn about it. The OpenTelemetry tracer of choice can learn about |
| 63 |
// this situation by using the migration.SkipContextSetup() |
| 64 |
// function. The tracer will receive an opportunity to set up the |
| 65 |
// context at a later stage. Usually after StartSpan() is finished, |
| 66 |
// users of the OpenTracing API are calling (either directly or |
| 67 |
// through the opentracing.StartSpanFromContext() helper function) the |
| 68 |
// opentracing.ContextWithSpan() function to insert the created |
| 69 |
// OpenTracing span into the context. At that time, the OpenTelemetry |
| 70 |
// tracer of choice has a chance of setting up the context through a |
| 71 |
// hook invoked inside the opentracing.ContextWithSpan() function. For |
| 72 |
// that to happen, the tracer should implement the |
| 73 |
// migration.DeferredContextSetupTracerExtension interface. This so |
| 74 |
// far explains the need for points 1. and 2. |
| 75 |
// |
| 76 |
// When the span is created with the OpenTelemetry API (with the |
| 77 |
// Start() function) then migration.SkipContextSetup() will return |
| 78 |
// false. This means that the tracer can do the usual setup of the |
| 79 |
// context, but it also should set up the active OpenTracing span in |
| 80 |
// the context. This is because OpenTracing API is not used at all in |
| 81 |
// the creation of the span, but the OpenTracing API may be used |
| 82 |
// during the time when the created OpenTelemetry span is current. For |
| 83 |
// this case to work, we need to also set up active OpenTracing span |
| 84 |
// in the context. This can be done with the ContextWithBridgeSpan() |
| 85 |
// function. This means that the OpenTelemetry tracer of choice needs |
| 86 |
// to have an access to the BridgeTracer instance. This should explain |
| 87 |
// the need for points 3. and 4. |
| 88 |
// |
| 89 |
// Another difference related to the Go context handling is in logging |
| 90 |
// - OpenTracing API does not take a context parameter in the |
| 91 |
// LogFields() function, so when the call to the function gets |
| 92 |
// translated to OpenTelemetry AddEvent() function, an empty context |
| 93 |
// is passed. |
| 94 |
package opentracing // import "go.opentelemetry.io/otel/bridge/opentracing" |