Debian Codegraph @

bridge/opentracing/doc.go

raw
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"