github.com/mdaxf/iac@v0.0.0-20240519030858-58a061660378/vendor_skip/go.opentelemetry.io/otel/trace/doc.go (about)

     1  // Copyright The OpenTelemetry Authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  /*
    16  Package trace provides an implementation of the tracing part of the
    17  OpenTelemetry API.
    18  
    19  To participate in distributed traces a Span needs to be created for the
    20  operation being performed as part of a traced workflow. In its simplest form:
    21  
    22  	var tracer trace.Tracer
    23  
    24  	func init() {
    25  		tracer = otel.Tracer("instrumentation/package/name")
    26  	}
    27  
    28  	func operation(ctx context.Context) {
    29  		var span trace.Span
    30  		ctx, span = tracer.Start(ctx, "operation")
    31  		defer span.End()
    32  		// ...
    33  	}
    34  
    35  A Tracer is unique to the instrumentation and is used to create Spans.
    36  Instrumentation should be designed to accept a TracerProvider from which it
    37  can create its own unique Tracer. Alternatively, the registered global
    38  TracerProvider from the go.opentelemetry.io/otel package can be used as
    39  a default.
    40  
    41  	const (
    42  		name    = "instrumentation/package/name"
    43  		version = "0.1.0"
    44  	)
    45  
    46  	type Instrumentation struct {
    47  		tracer trace.Tracer
    48  	}
    49  
    50  	func NewInstrumentation(tp trace.TracerProvider) *Instrumentation {
    51  		if tp == nil {
    52  			tp = otel.TracerProvider()
    53  		}
    54  		return &Instrumentation{
    55  			tracer: tp.Tracer(name, trace.WithInstrumentationVersion(version)),
    56  		}
    57  	}
    58  
    59  	func operation(ctx context.Context, inst *Instrumentation) {
    60  		var span trace.Span
    61  		ctx, span = inst.tracer.Start(ctx, "operation")
    62  		defer span.End()
    63  		// ...
    64  	}
    65  
    66  # API Implementations
    67  
    68  This package does not conform to the standard Go versioning policy; all of its
    69  interfaces may have methods added to them without a package major version bump.
    70  This non-standard API evolution could surprise an uninformed implementation
    71  author. They could unknowingly build their implementation in a way that would
    72  result in a runtime panic for their users that update to the new API.
    73  
    74  The API is designed to help inform an instrumentation author about this
    75  non-standard API evolution. It requires them to choose a default behavior for
    76  unimplemented interface methods. There are three behavior choices they can
    77  make:
    78  
    79    - Compilation failure
    80    - Panic
    81    - Default to another implementation
    82  
    83  All interfaces in this API embed a corresponding interface from
    84  [go.opentelemetry.io/otel/trace/embedded]. If an author wants the default
    85  behavior of their implementations to be a compilation failure, signaling to
    86  their users they need to update to the latest version of that implementation,
    87  they need to embed the corresponding interface from
    88  [go.opentelemetry.io/otel/trace/embedded] in their implementation. For
    89  example,
    90  
    91  	import "go.opentelemetry.io/otel/trace/embedded"
    92  
    93  	type TracerProvider struct {
    94  		embedded.TracerProvider
    95  		// ...
    96  	}
    97  
    98  If an author wants the default behavior of their implementations to panic, they
    99  can embed the API interface directly.
   100  
   101  	import "go.opentelemetry.io/otel/trace"
   102  
   103  	type TracerProvider struct {
   104  		trace.TracerProvider
   105  		// ...
   106  	}
   107  
   108  This option is not recommended. It will lead to publishing packages that
   109  contain runtime panics when users update to newer versions of
   110  [go.opentelemetry.io/otel/trace], which may be done with a trasitive
   111  dependency.
   112  
   113  Finally, an author can embed another implementation in theirs. The embedded
   114  implementation will be used for methods not defined by the author. For example,
   115  an author who wants to default to silently dropping the call can use
   116  [go.opentelemetry.io/otel/trace/noop]:
   117  
   118  	import "go.opentelemetry.io/otel/trace/noop"
   119  
   120  	type TracerProvider struct {
   121  		noop.TracerProvider
   122  		// ...
   123  	}
   124  
   125  It is strongly recommended that authors only embed
   126  [go.opentelemetry.io/otel/trace/noop] if they choose this default behavior.
   127  That implementation is the only one OpenTelemetry authors can guarantee will
   128  fully implement all the API interfaces when a user updates their API.
   129  */
   130  package trace // import "go.opentelemetry.io/otel/trace"