| 1 |
// Copyright The OpenTelemetry Authors |
| 2 |
// SPDX-License-Identifier: Apache-2.0 |
| 3 |
|
| 4 |
package trace // import "go.opentelemetry.io/otel/trace" |
| 5 |
|
| 6 |
import "go.opentelemetry.io/otel/trace/embedded" |
| 7 |
|
| 8 |
// TracerProvider provides Tracers that are used by instrumentation code to |
| 9 |
// trace computational workflows. |
| 10 |
// |
| 11 |
// A TracerProvider is the collection destination of all Spans from Tracers it |
| 12 |
// provides, it represents a unique telemetry collection pipeline. How that |
| 13 |
// pipeline is defined, meaning how those Spans are collected, processed, and |
| 14 |
// where they are exported, depends on its implementation. Instrumentation |
| 15 |
// authors do not need to define this implementation, rather just use the |
| 16 |
// provided Tracers to instrument code. |
| 17 |
// |
| 18 |
// Commonly, instrumentation code will accept a TracerProvider implementation |
| 19 |
// at runtime from its users or it can simply use the globally registered one |
| 20 |
// (see https://pkg.go.dev/go.opentelemetry.io/otel#GetTracerProvider). |
| 21 |
// |
| 22 |
// Warning: Methods may be added to this interface in minor releases. See |
| 23 |
// package documentation on API implementation for information on how to set |
| 24 |
// default behavior for unimplemented methods. |
| 25 |
type TracerProvider interface { |
| 26 |
// Users of the interface can ignore this. This embedded type is only used |
| 27 |
// by implementations of this interface. See the "API Implementations" |
| 28 |
// section of the package documentation for more information. |
| 29 |
embedded.TracerProvider |
| 30 |
|
| 31 |
// Tracer returns a unique Tracer scoped to be used by instrumentation code |
| 32 |
// to trace computational workflows. The scope and identity of that |
| 33 |
// instrumentation code is uniquely defined by the name and options passed. |
| 34 |
// |
| 35 |
// The passed name needs to uniquely identify instrumentation code. |
| 36 |
// Therefore, it is recommended that name is the Go package name of the |
| 37 |
// library providing instrumentation (note: not the code being |
| 38 |
// instrumented). Instrumentation libraries can have multiple versions, |
| 39 |
// therefore, the WithInstrumentationVersion option should be used to |
| 40 |
// distinguish these different codebases. Additionally, instrumentation |
| 41 |
// libraries may sometimes use traces to communicate different domains of |
| 42 |
// workflow data (i.e. using spans to communicate workflow events only). If |
| 43 |
// this is the case, the WithScopeAttributes option should be used to |
| 44 |
// uniquely identify Tracers that handle the different domains of workflow |
| 45 |
// data. |
| 46 |
// |
| 47 |
// If the same name and options are passed multiple times, the same Tracer |
| 48 |
// will be returned (it is up to the implementation if this will be the |
| 49 |
// same underlying instance of that Tracer or not). It is not necessary to |
| 50 |
// call this multiple times with the same name and options to get an |
| 51 |
// up-to-date Tracer. All implementations will ensure any TracerProvider |
| 52 |
// configuration changes are propagated to all provided Tracers. |
| 53 |
// |
| 54 |
// If name is empty, then an implementation defined default name will be |
| 55 |
// used instead. |
| 56 |
// |
| 57 |
// This method is safe to call concurrently. |
| 58 |
Tracer(name string, options ...TracerOption) Tracer |
| 59 |
} |