Documentation
¶
Overview ¶
Package tracer helps with the propagation of the tracer 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 tracer 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 tracer package a Tracer instance must be created:
tracer, tracerCloser, err := tracer.NewTracer(&tracer.Options{
Enabled: true,
Endpoint: "127.0.0.1:6831",
ServiceName: "mop",
})
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, _, mctx := tracer.StartSpanFromContext(mctx, "operation-name", nil)
Once the operation is finished, the open span should be finished:
span.Finish()
The tracer 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 := tracer.NewLoggerWithTraceID(mctx, s.logger)
// ...
logger.Info("some message")
Which will result in following log line (if the context contains tracer 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 log.Logger) log.Logger
- 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 log.Logger, ...) (opentracing.Span, log.Logger, 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 tracer context. TraceContextHeaderName = "cluster-trace-id" // TraceBaggageHeaderPrefix is the prefix for http headers used to propagate baggage. TraceBaggageHeaderPrefix = "clusterctx-" )
const LogField = "traceID"
LogField is the key in log message field that holds tracer id value.
Variables ¶
var ( // ErrContextNotFound is returned when tracer context is not present // in p2p Headers or context. ErrContextNotFound = errors.New("tracer context not found") )
Functions ¶
func FromContext ¶
FromContext return tracer span context from go context. If the tracer 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 tracer span context stored from go context.
Types ¶
type Tracer ¶
type Tracer struct {
// contains filtered or unexported fields
}
Tracer connect to a tracer server and handles tracer 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 tracer span context to provided HTTP headers from the go context. If the tracer span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) AddContextHeader ¶
AddContextHeader adds a tracer span context to provided p2p Headers from the go context. If the tracer span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) FromHTTPHeaders ¶
FromHTTPHeaders returns tracer span context from HTTP headers. If the tracer span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) FromHeaders ¶
FromHeaders returns tracer span context from p2p Headers. If the tracer span context is not present in go context, ErrContextNotFound is returned.
func (*Tracer) StartSpanFromContext ¶
func (t *Tracer) StartSpanFromContext(ctx context.Context, operationName string, l log.Logger, opts ...opentracing.StartSpanOption) (opentracing.Span, log.Logger, context.Context)
StartSpanFromContext starts a new tracer 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 tracer span context if they are found in HTTP headers. If the tracer 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 tracer span context if they are found in p2p Headers. If the tracer span context is not present in go context, ErrContextNotFound is returned.
Source Files