github.com/ethersphere/bee/v2@v2.2.0/pkg/tracing/doc.go (about)

     1  // Copyright 2020 The Swarm Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package tracing helps with the propagation of the tracing span through context
     7  in the system. It does this for operations contained to single node, as well as
     8  across nodes, by injecting special headers.
     9  
    10  To use the tracing package, a Tracer instance must be created, which contains
    11  functions for starting new span contexts, injecting them in other data, and
    12  extracting the active span them from the context.
    13  
    14  To use the tracing package a Tracer instance must be created:
    15  
    16  	tracer, tracerCloser, err := tracing.NewTracer(&tracing.Options{
    17  		Enabled:     true,
    18  		Endpoint:    "127.0.0.1:6831",
    19  		ServiceName: "bee",
    20  	})
    21  	if err != nil {
    22  		// handle error
    23  	}
    24  	defer tracerCloser.Close()
    25  	// ...
    26  
    27  The tracer instance contains functions for starting new span contexts, injecting
    28  them in other data, and extracting the active span them from the context:
    29  
    30  	span, _, ctx := tracer.StartSpanFromContext(ctx, "operation-name", nil)
    31  
    32  Once the operation is finished, the open span should be finished:
    33  
    34  	span.Finish()
    35  
    36  The tracing package also provides a function for creating a logger which will
    37  inject a "traceID" field entry to the log line, which helps in finding out which
    38  log lines belong to a specific trace.
    39  
    40  To create a logger with trace just wrap an existing logger:
    41  
    42  	logger := tracing.NewLoggerWithTraceID(ctx, s.logger)
    43  	// ...
    44  	logger.Info("some message")
    45  
    46  Which will result in following log line (if the context contains tracing
    47  information):
    48  
    49  	time="2015-09-07T08:48:33Z" level=info msg="some message" traceID=ed65818cc1d30c
    50  */
    51  package tracing