Documentation
¶
Overview ¶
Package tracing helps with the propagation of the tracing span through context in the system. It does this for operations contained to single node, as well as across nodes, by injecting special headers.
To use the tracing package, a Tracer instance must be created, which contains functions for starting new span contexts, injecting them in other data, and extracting the active span them from the context.
To use the tracing package a Tracer instance must be created:
tracer, tracerCloser, err := tracing.NewTracer(&tracing.Options{ Enabled: true, Endpoint: "127.0.0.1:16831", ServiceName: "bee", }) if err != nil { // handle error } defer tracerCloser.Close() // ...
The tracer instance contains functions for starting new span contexts, injecting them in other data, and extracting the active span them from the context:
span, _, ctx := tracer.StartSpanFromContext(ctx, "operation-name", nil)
Once the operation is finished, the open span should be finished:
span.Finish()
The tracing package also provides a function for creating a logger which will inject a "traceID" field entry to the log line, which helps in finding out which log lines belong to a specific trace.
To create a logger with trace just wrap an existing logger:
logger := tracing.NewLoggerWithTraceID(ctx, s.logger) // ... logger.Info("some message")
Which will result in following log line (if the context contains tracing information):
time="2015-09-07T08:48:33Z" level=info msg="some message" traceID=ed65818cc1d30c
Index ¶
- Constants
- Variables
- func FromContext(ctx context.Context) opentracing.SpanContext
- func NewLoggerWithTraceID(ctx context.Context, l logging.Logger) *logrus.Entry
- func WithContext(ctx context.Context, c opentracing.SpanContext) context.Context
- type Options
- type Tracer
- func (t *Tracer) AddContextHTTPHeader(ctx context.Context, headers http.Header) error
- func (t *Tracer) AddContextHeader(ctx context.Context, headers p2p.Headers) error
- func (t *Tracer) FromHTTPHeaders(headers http.Header) (opentracing.SpanContext, error)
- func (t *Tracer) FromHeaders(headers p2p.Headers) (opentracing.SpanContext, error)
- func (t *Tracer) StartSpanFromContext(ctx context.Context, operationName string, l logging.Logger, ...) (opentracing.Span, *logrus.Entry, context.Context)
- func (t *Tracer) WithContextFromHTTPHeaders(ctx context.Context, headers http.Header) (context.Context, error)
- func (t *Tracer) WithContextFromHeaders(ctx context.Context, headers p2p.Headers) (context.Context, error)
Constants ¶
const ( // TraceContextHeaderName is the http header name used to propagate tracing context. TraceContextHeaderName = "swarm-trace-id" // TraceBaggageHeaderPrefix is the prefix for http headers used to propagate baggage. TraceBaggageHeaderPrefix = "swarmctx-" )
const LogField = "traceID"
LogField is the key in log message field that holds tracing id value.
Variables ¶
var ( // ErrContextNotFound is returned when tracing context is not present // in p2p Headers or context. ErrContextNotFound = errors.New("tracing context not found") )
Functions ¶
func FromContext ¶
FromContext return tracing span context from go context. If the tracing span context is not present in go context, nil is returned.
func NewLoggerWithTraceID ¶
NewLoggerWithTraceID creates a new log Entry with "traceID" field added if it exists in tracing span context stored from go context.
Types ¶
type Tracer ¶
type Tracer struct {
// contains filtered or unexported fields
}
Tracer connect to a tracing server and handles tracing spans and contexts by using opentracing Tracer.
func NewTracer ¶
NewTracer creates a new Tracer and returns a closer which needs to be closed when the Tracer is no longer used to flush remaining traces.
func (*Tracer) AddContextHTTPHeader ¶
AddContextHTTPHeader adds a tracing span context to provided HTTP headers from the go context. If the tracing span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) AddContextHeader ¶
AddContextHeader adds a tracing span context to provided p2p Headers from the go context. If the tracing span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) FromHTTPHeaders ¶
FromHTTPHeaders returns tracing span context from HTTP headers. If the tracing span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) FromHeaders ¶
FromHeaders returns tracing span context from p2p Headers. If the tracing span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) StartSpanFromContext ¶
func (t *Tracer) StartSpanFromContext(ctx context.Context, operationName string, l logging.Logger, opts ...opentracing.StartSpanOption) (opentracing.Span, *logrus.Entry, context.Context)
StartSpanFromContext starts a new tracing span that is either a root one or a child of existing one from the provided Context. If logger is provided, a new log Entry will be returned with "traceID" log field.
func (*Tracer) WithContextFromHTTPHeaders ¶
func (t *Tracer) WithContextFromHTTPHeaders(ctx context.Context, headers http.Header) (context.Context, error)
WithContextFromHTTPHeaders returns a new context with injected tracing span context if they are found in HTTP headers. If the tracing span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) WithContextFromHeaders ¶
func (t *Tracer) WithContextFromHeaders(ctx context.Context, headers p2p.Headers) (context.Context, error)
WithContextFromHeaders returns a new context with injected tracing span context if they are found in p2p Headers. If the tracing span context is not present in go context, ErrContextNotFound is returned.