tracing

func AnnotateTrace ¶

func AnnotateTrace()

AnnotateTrace adds an annotation to the golang executation tracer by calling a no-op cgo function.

func ChildSpan ¶

func ChildSpan(ctx context.Context, opName string) (context.Context, opentracing.Span)

ChildSpan opens a span as a child of the current span in the context (if there is one). The span's tags are inherited from the ctx's log tags automatically.

Returns the new context and the new span (if any). The span should be closed via FinishSpan.

func ChildSpanSeparateRecording ¶

func ChildSpanSeparateRecording(
	ctx context.Context, opName string,
) (context.Context, opentracing.Span)

ChildSpanSeparateRecording is like ChildSpan but the new span has separate recording (see StartChildSpan).

func ContextWithRecordingSpan ¶

func ContextWithRecordingSpan(
	ctx context.Context, opName string,
) (retCtx context.Context, getRecording func() Recording, cancel func())

ContextWithRecordingSpan returns a context with an embedded trace span which returns its contents when getRecording is called and must be stopped by calling the cancel method when done with the context (getRecording() needs to be called before cancel()).

Note that to convert the recorded spans into text, you can use Recording.String(). Tests can also use FindMsgInRecording().

func EnsureChildSpan ¶

func EnsureChildSpan(
	ctx context.Context, tracer opentracing.Tracer, name string,
) (context.Context, opentracing.Span)

EnsureChildSpan is the same as EnsureContext, except it creates a child span for the input context if the input context already has an active trace.

The caller is responsible for closing the span (via Span.Finish).

func EnsureContext ¶

func EnsureContext(
	ctx context.Context, tracer opentracing.Tracer, opName string,
) (context.Context, func())

EnsureContext checks whether the given context.Context contains a Span. If not, it creates one using the provided Tracer and wraps it in the returned Span. The returned closure must be called after the request has been fully processed.

Note that, if there's already a span in the context, this method does nothing even if the current context's log tags are different from that span's tags.

func FindMsgInRecording ¶

func FindMsgInRecording(recording Recording, msg string) int

FindMsgInRecording returns the index of the first span containing msg in its logs, or -1 if no span is found.

func FinishSpan ¶

func FinishSpan(span opentracing.Span)

FinishSpan closes the given span (if not nil). It is a convenience wrapper for span.Finish() which tolerates nil spans.

func ForkCtxSpan ¶

func ForkCtxSpan(ctx context.Context, opName string) (context.Context, opentracing.Span)

ForkCtxSpan checks if ctx has a Span open; if it does, it creates a new Span that "follows from" the original Span. This allows the resulting context to be used in an async task that might outlive the original operation.

Returns the new context and the new span (if any). The span should be closed via FinishSpan.

See also ChildSpan() for a "parent-child relationship".

func ImportRemoteSpans ¶

func ImportRemoteSpans(os opentracing.Span, remoteSpans []RecordedSpan) error

ImportRemoteSpans adds RecordedSpan data to the recording of the given span; these spans will be part of the result of GetRecording. Used to import recorded traces from other nodes.

func IsBlackHoleSpan ¶

func IsBlackHoleSpan(s opentracing.Span) bool

IsBlackHoleSpan returns true if events for this span are just dropped. This is the case when tracing is disabled and we're not recording. Tracing clients can use this method to figure out if they can short-circuit some tracing-related work that would be discarded anyway.

func IsNoopContext ¶

func IsNoopContext(spanCtx opentracing.SpanContext) bool

IsNoopContext returns true if the span context is from a "no-op" span. If this is true, any span derived from this context will be a "black hole span".

func IsRecordable ¶

func IsRecordable(os opentracing.Span) bool

IsRecordable returns true if {Start,Stop}Recording() can be called on this span.

In other words, this tests if the span is our custom type, and not a noopSpan or anything else.

func IsRecording ¶

func IsRecording(s opentracing.Span) bool

IsRecording returns true if the span is recording its events.

func LogTags ¶

func LogTags(tags *logtags.Buffer) opentracing.StartSpanOption

LogTags returns a StartSpanOption that sets the span tags to the given log tags. When applied, the returned option will apply any logtag name->span tag name remapping that has been registered via RegisterTagRemapping.

func LogTagsFromCtx ¶

func LogTagsFromCtx(ctx context.Context) opentracing.StartSpanOption

LogTagsFromCtx returns a StartSpanOption that sets the span tags to the log tags in the context.

func RegisterTagRemapping ¶

func RegisterTagRemapping(logTag, spanTag string)

RegisterTagRemapping sets the span tag name that corresponds to the given log tag name. Should be called as part of an init() function.

func SetSpanStats ¶

func SetSpanStats(os opentracing.Span, stats SpanStats)

SetSpanStats sets the stats on a span. stats.Stats() will also be added to the span tags.

func StartChildSpan ¶

func StartChildSpan(
	opName string, parentSpan opentracing.Span, logTags *logtags.Buffer, separateRecording bool,
) opentracing.Span

StartChildSpan creates a child span of the given parent span. This is functionally equivalent to: parentSpan.Tracer().(*Tracer).StartSpan(opName, opentracing.ChildOf(parentSpan.Context())) Compared to that, it's more efficient, particularly in terms of memory allocations; among others, it saves the call to parentSpan.Context.

This only works for creating children of local parents (i.e. the caller needs to have a reference to the parent span).

If separateRecording is true and the parent span is recording, the child's recording will not be part of the parent's recording. This is useful when the child's recording will be reported to a collector separate from the parent's recording; for example DistSQL processors each report their own recording, and we don't want the parent's recording to include a child's because then we might double-report that child.

func StartRecording ¶

func StartRecording(os opentracing.Span, recType RecordingType)

StartRecording enables recording on the span. Events from this point forward are recorded; also, all direct and indirect child spans started from now on will be part of the same recording.

Recording is not supported by noop spans; to ensure a real span is always created, use the Recordable option to StartSpan.

If recording was already started on this span (either directly or because a parent span is recording), the old recording is lost.

func StartSnowballTrace ¶

func StartSnowballTrace(
	ctx context.Context, tracer opentracing.Tracer, opName string,
) (context.Context, opentracing.Span)

StartSnowballTrace takes in a context and returns a derived one with a "snowball span" in it. The caller takes ownership of this span from the returned context and is in charge of Finish()ing it. The span has recording enabled.

TODO(andrei): remove this method once EXPLAIN(TRACE) is gone.

func StopRecording ¶

func StopRecording(os opentracing.Span)

StopRecording disables recording on this span. Child spans that were created since recording was started will continue to record until they finish.

Calling this after StartRecording is not required; the recording will go away when all the spans finish.

StopRecording() can be called on a Finish()ed span.

func TestingCheckRecordedSpans ¶

func TestingCheckRecordedSpans(recSpans []RecordedSpan, expected string) error

TestingCheckRecordedSpans checks whether a recording looks like an expected one represented by a string with one line per expected span and one line per expected event (i.e. log message).

Use with something like:

	 if err := TestingCheckRecordedSpans(tracing.GetRecording(span), `
    span root:
      event: a
      event: c
    span child:
      event: [ambient] b
  `); err != nil {
  	t.Fatal(err)
  }

The event lines can (and generally should) omit the file:line part that they might contain (depending on the level at which they were logged).

Note: this test function is in this file because it needs to be used by both tests in the tracing package and tests outside of it, and the function itself depends on tracing.