trace

Documentation

Overview

Package trace provides a tracing API that in turn invokes both the `golang.org/x/net/trace` API and creates an opentracing span if appropriate.

This is similar to the github.com/sourcegraph/sourcegraph/internal/trace package in the main repo, and it may make sense to factor both out into a common package at some point.

Index

• func ContextWithTrace(ctx context.Context, tr *Trace) context.Context
• func GetOpenTracer(ctx context.Context, tracer opentracing.Tracer) opentracing.Tracer
• func Printf(key, f string, args ...interface{}) log.Field
• func StartSpanFromContext(ctx context.Context, operationName string, opts ...opentracing.StartSpanOption) (opentracing.Span, context.Context)
• func StartSpanFromContextWithTracer(ctx context.Context, tracer opentracing.Tracer, operationName string, ...) (opentracing.Span, context.Context)
• func WithOpenTracingEnabled(ctx context.Context, enableOpenTracing bool) context.Context
• type Trace
  • func New(ctx context.Context, family, title string) (*Trace, context.Context)
  • func TraceFromContext(ctx context.Context) *Trace
  • func (t *Trace) Finish()
  • func (t *Trace) LazyLog(x fmt.Stringer, sensitive bool)
  • func (t *Trace) LazyPrintf(format string, a ...interface{})
  • func (t *Trace) LogFields(fields ...log.Field)
  • func (t *Trace) SetError(err error)
• type Tracer
  • func (t Tracer) New(ctx context.Context, family, title string) (*Trace, context.Context)

Functions

func ContextWithTrace

func ContextWithTrace(ctx context.Context, tr *Trace) context.Context

ContextWithTrace returns a new context.Context that holds a reference to trace's SpanContext.

func GetOpenTracer

func GetOpenTracer(ctx context.Context, tracer opentracing.Tracer) opentracing.Tracer

GetOpenTracer returns the tracer to actually use depending on whether isOpenTracingEnabled(ctx) returns true or false. If false, this returns the NoopTracer.

func Printf

func Printf(key, f string, args ...interface{}) log.Field

Printf is an opentracing log.Field which is a LazyLogger. So the format string will only be evaluated if the trace is collected. In the case of net/trace, it will only be evaluated on page load.

func StartSpanFromContext

func StartSpanFromContext(ctx context.Context, operationName string, opts ...opentracing.StartSpanOption) (opentracing.Span, context.Context)

StartSpanFromContext starts a span using the tracer returned by GetOpenTracer.

func StartSpanFromContextWithTracer

func StartSpanFromContextWithTracer(ctx context.Context, tracer opentracing.Tracer, operationName string, opts ...opentracing.StartSpanOption) (opentracing.Span, context.Context)

StartSpanFromContext starts a span using the tracer returned by invoking GetOpenTracer with the passed-in tracer.

func WithOpenTracingEnabled

func WithOpenTracingEnabled(ctx context.Context, enableOpenTracing bool) context.Context

Types

type Trace

type Trace struct {
	// contains filtered or unexported fields
}

Trace is a combined version of golang.org/x/net/trace.Trace and opentracing.Span. Use New to construct one.

func New

func New(ctx context.Context, family, title string) (*Trace, context.Context)

func TraceFromContext

func TraceFromContext(ctx context.Context) *Trace

TraceFromContext returns the Trace previously associated with ctx, or nil if no such Trace could be found.

func (*Trace) Finish

func (t *Trace) Finish()

Finish declares that this trace and span is complete. The trace should not be used after calling this method.

func (*Trace) LazyLog

func (t *Trace) LazyLog(x fmt.Stringer, sensitive bool)

func (*Trace) LazyPrintf

func (t *Trace) LazyPrintf(format string, a ...interface{})

LazyPrintf evaluates its arguments with fmt.Sprintf each time the /debug/requests page is rendered. Any memory referenced by a will be pinned until the trace is finished and later discarded.

func (*Trace) LogFields

func (t *Trace) LogFields(fields ...log.Field)

LogFields logs fields to the opentracing.Span as well as the nettrace.Trace.

func (*Trace) SetError

func (t *Trace) SetError(err error)

SetError declares that this trace and span resulted in an error.

type Tracer

type Tracer struct {
	Tracer opentracing.Tracer
}

A Tracer for trace creation, parameterised over an opentracing.Tracer. Use this if you don't want to use the global tracer.

func (Tracer) New

func (t Tracer) New(ctx context.Context, family, title string) (*Trace, context.Context)

New returns a new Trace with the specified family and title.