tracing

package
v1.1.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2018 License: Apache-2.0 Imports: 28 Imported by: 1,969

Documentation

Overview

Package tracing is a generated protocol buffer package.

It is generated from these files: 

cockroach/pkg/util/tracing/recorded_span.proto

It has these top-level messages: 

RecordedSpan

Index

Constants

View Source 
const Snowball = "sb"

Snowball is set as Baggage on traces which are used for snowball tracing.

Variables

View Source 
var (
	ErrInvalidLengthRecordedSpan = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowRecordedSpan   = fmt.Errorf("proto: integer overflow")
)
View Source 
var Recordable opentracing.StartSpanOption = recordableOption{}

Recordable is a StartSpanOption that forces creation of a real span.

When tracing is disabled all spans are noopSpans; these spans aren't capable of recording, so this option should be passed to StartSpan if the caller wants to be able to call StartRecording on the resulting span.

Functions

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).

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

func ContextWithRecordingSpan added in v1.1.0 

func ContextWithRecordingSpan(
	ctx context.Context, opName string,
) (retCtx context.Context, getRecording func() []RecordedSpan, 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. Note that to convert the recorded spans into text, you can use FormatRecordedSpans.

func EnsureContext 

func EnsureContext(
	ctx context.Context, tracer opentracing.Tracer, name 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.

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 FormatRecordedSpans added in v1.1.0 

func FormatRecordedSpans(spans []RecordedSpan) string

FormatRecordedSpans formats the given spans for human consumption, showing the relationship using nesting and times as both relative to the previous event and cumulative.

TODO(andrei): this should be unified with SessionTracing.GenerateSessionTraceVTable.

func ImportRemoteSpans added in v1.1.0 

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 added in v1.1.0 

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 added in v1.1.0 

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 added in v1.1.0 

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 StartChildSpan added in v1.1.0 

func StartChildSpan(
	operationName string, parentSpan opentracing.Span, 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, we start a new recording for the child span. If separateRecording is false (the default), then the child span will be part of the same recording.

func StartRecording added in v1.1.0 

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 Force 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, error)

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 added in v1.1.0 

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.

func TestingCheckRecordedSpans added in v1.1.0 

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.

Types

type RecordedSpan added in v1.1.0 

type RecordedSpan struct {
	// ID of the trace; spans that are part of the same hierarchy share
	// the same trace ID.
	TraceID uint64 `protobuf:"varint,1,opt,name=trace_id,json=traceId,proto3" json:"trace_id,omitempty"`
	// ID of the span.
	SpanID uint64 `protobuf:"varint,2,opt,name=span_id,json=spanId,proto3" json:"span_id,omitempty"`
	// Span ID of the parent span.
	ParentSpanID uint64 `protobuf:"varint,3,opt,name=parent_span_id,json=parentSpanId,proto3" json:"parent_span_id,omitempty"`
	// Operation name.
	Operation string `protobuf:"bytes,4,opt,name=operation,proto3" json:"operation,omitempty"`
	// Baggage items get passed from parent to child spans (even through gRPC).
	// Notably, snowball tracing uses a special `sb` baggage item.
	Baggage map[string]string `` /* 148-byte string literal not displayed */
	// Tags associated with the span.
	Tags map[string]string `` /* 142-byte string literal not displayed */
	// Time when the span was started.
	StartTime time.Time `protobuf:"bytes,7,opt,name=start_time,json=startTime,stdtime" json:"start_time"`
	// Duration in nanoseconds; 0 if the span is not finished.
	Duration time.Duration `protobuf:"bytes,8,opt,name=duration,stdduration" json:"duration"`
	// Events logged in the span.
	Logs []RecordedSpan_LogRecord `protobuf:"bytes,9,rep,name=logs" json:"logs"`
}

RecordedSpan is a span that is part of a recording. It can be transferred over the wire for snowball tracing.

func GetRecording added in v1.1.0 

func GetRecording(os opentracing.Span) []RecordedSpan

GetRecording retrieves the current recording, if the span has recording enabled. This can be called while spans that are part of the record are still open; it can run concurrently with operations on those spans.

func (*RecordedSpan) Descriptor added in v1.1.0 

func (*RecordedSpan) Descriptor() ([]byte, []int)

func (*RecordedSpan) Marshal added in v1.1.0 

func (m *RecordedSpan) Marshal() (dAtA []byte, err error)

func (*RecordedSpan) MarshalTo added in v1.1.0 

func (m *RecordedSpan) MarshalTo(dAtA []byte) (int, error)

func (*RecordedSpan) ProtoMessage added in v1.1.0 

func (*RecordedSpan) ProtoMessage()

func (*RecordedSpan) Reset added in v1.1.0 

func (m *RecordedSpan) Reset()

func (*RecordedSpan) Size added in v1.1.0 

func (m *RecordedSpan) Size() (n int)

func (*RecordedSpan) String added in v1.1.0 

func (m *RecordedSpan) String() string

func (*RecordedSpan) Unmarshal added in v1.1.0 

func (m *RecordedSpan) Unmarshal(dAtA []byte) error

type RecordedSpan_LogRecord added in v1.1.0 

type RecordedSpan_LogRecord struct {
	// Time of the log record.
	Time time.Time `protobuf:"bytes,1,opt,name=time,stdtime" json:"time"`
	// Fields with values converted to strings.
	Fields []RecordedSpan_LogRecord_Field `protobuf:"bytes,2,rep,name=fields" json:"fields"`
}

func (*RecordedSpan_LogRecord) Descriptor added in v1.1.0 

func (*RecordedSpan_LogRecord) Descriptor() ([]byte, []int)

func (*RecordedSpan_LogRecord) Marshal added in v1.1.0 

func (m *RecordedSpan_LogRecord) Marshal() (dAtA []byte, err error)

func (*RecordedSpan_LogRecord) MarshalTo added in v1.1.0 

func (m *RecordedSpan_LogRecord) MarshalTo(dAtA []byte) (int, error)

func (*RecordedSpan_LogRecord) ProtoMessage added in v1.1.0 

func (*RecordedSpan_LogRecord) ProtoMessage()

func (*RecordedSpan_LogRecord) Reset added in v1.1.0 

func (m *RecordedSpan_LogRecord) Reset()

func (*RecordedSpan_LogRecord) Size added in v1.1.0 

func (m *RecordedSpan_LogRecord) Size() (n int)

func (*RecordedSpan_LogRecord) String added in v1.1.0 

func (m *RecordedSpan_LogRecord) String() string

func (*RecordedSpan_LogRecord) Unmarshal added in v1.1.0 

func (m *RecordedSpan_LogRecord) Unmarshal(dAtA []byte) error

type RecordedSpan_LogRecord_Field added in v1.1.0 

type RecordedSpan_LogRecord_Field struct {
	Key   string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
	Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
}

func (*RecordedSpan_LogRecord_Field) Descriptor added in v1.1.0 

func (*RecordedSpan_LogRecord_Field) Descriptor() ([]byte, []int)

func (*RecordedSpan_LogRecord_Field) Marshal added in v1.1.0 

func (m *RecordedSpan_LogRecord_Field) Marshal() (dAtA []byte, err error)

func (*RecordedSpan_LogRecord_Field) MarshalTo added in v1.1.0 

func (m *RecordedSpan_LogRecord_Field) MarshalTo(dAtA []byte) (int, error)

func (*RecordedSpan_LogRecord_Field) ProtoMessage added in v1.1.0 

func (*RecordedSpan_LogRecord_Field) ProtoMessage()

func (*RecordedSpan_LogRecord_Field) Reset added in v1.1.0 

func (m *RecordedSpan_LogRecord_Field) Reset()

func (*RecordedSpan_LogRecord_Field) Size added in v1.1.0 

func (m *RecordedSpan_LogRecord_Field) Size() (n int)

func (*RecordedSpan_LogRecord_Field) String added in v1.1.0 

func (m *RecordedSpan_LogRecord_Field) String() string

func (*RecordedSpan_LogRecord_Field) Unmarshal added in v1.1.0 

func (m *RecordedSpan_LogRecord_Field) Unmarshal(dAtA []byte) error

type RecordingType added in v1.1.0 

type RecordingType bool

RecordingType is the type of recording that a span might be performing. 

const (
	// SnowballRecording means that remote child spans (generally opened through
	// RPCs) are also recorded.
	SnowballRecording RecordingType = true
	// SingleNodeRecording means that only spans on the current node are recorded.
	SingleNodeRecording RecordingType = false
)

type Tracer added in v1.1.0 

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

Tracer is our own custom implementation of opentracing.Tracer. It supports:

  • forwarding events to x/net/trace instances

  • recording traces. Recording is started automatically for spans that have the Snowball baggage and can be started explicitly as well. Recorded events can be retrieved at any time.

  • lightstep traces. This is implemented by maintaining a "shadow" lightstep span inside each of our spans.

Even when tracing is disabled, we still use this Tracer (with x/net/trace and lightstep disabled) because of its recording capability (snowball tracing needs to work in all cases).

Tracer is currently stateless so we could have a single instance; however, this won't be the case if the cluster settings move away from using global state.

func NewTracer 

func NewTracer() *Tracer

NewTracer creates a Tracer. It initially tries to run with minimal overhead and collects essentially nothing; use Configure() to enable various tracing backends.

func (*Tracer) Close added in v1.1.0 

func (t *Tracer) Close()

Close cleans up any resources associated with a Tracer.

func (*Tracer) Configure added in v1.1.0 

func (t *Tracer) Configure(sv *settings.Values)

Configure sets up the Tracer according to the cluster settings (and keeps it updated if they change).

func (*Tracer) Extract added in v1.1.0 

func (t *Tracer) Extract(format interface{}, carrier interface{}) (opentracing.SpanContext, error)

Extract is part of the opentracing.Tracer interface. It always returns a valid context, even in error cases (this is assumed by the grpc-opentracing interceptor).

func (*Tracer) Inject added in v1.1.0 

func (t *Tracer) Inject(
	osc opentracing.SpanContext, format interface{}, carrier interface{},
) error

Inject is part of the opentracing.Tracer interface.

func (*Tracer) SetForceRealSpans added in v1.1.0 

func (t *Tracer) SetForceRealSpans(v bool) bool

SetForceRealSpans sets forceRealSpans option to v and returns the previous value.

func (*Tracer) StartSpan added in v1.1.0 

func (t *Tracer) StartSpan(
	operationName string, opts ...opentracing.StartSpanOption,
) opentracing.Span

StartSpan is part of the opentracing.Tracer interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.