span

Documentation

Overview

Package span provides access to OpenTelemetry Span objects for the purpose of logging events for the gostdlib packages.

OTEL spans are not well defined. For our purposes, we will generally create a child span on interesting function calls within a package.

Index

• type Span
  • func Get(ctx context.Context) Span
  • func New(ctx context.Context, name string, options ...trace.SpanStartOption) (context.Context, Span)
  • func (s Span) End()
  • func (s Span) Error(e error, keyValues ...any) error
  • func (s Span) Event(name string, keyValues ...any) error
  • func (s Span) IsRecording() bool
  • func (s Span) Status(code codes.Code, description string)

Types

type Span

type Span struct {
	// Span is the OTEL trace.Span.
	Span trace.Span
}

Span represents an OTEL span for recording events to. This superclass handles noops for the trace.Span and events we record. You get a child Span object by using New() or an existing Span object by using Get(). We have standardized how we records events and other type of actions on the span. The original Span object is available for other needs.

func Get

func Get(ctx context.Context) Span

Get returns the Span for recording events. This retrieves the OTEL span from the Context object. If the OTEL span is a noop, then all events will also be a noop.

func New

func New(ctx context.Context, name string, options ...trace.SpanStartOption) (context.Context, Span)

New creates a new child span object from the span stored in Context. If that Span is a noOp, the child span will be a noop too.

func (Span) End

func (s Span) End()

End ends the span.

func (Span) Error

func (s Span) Error(e error, keyValues ...any) error

Error records an error on the Span. This does not set the status of the span. If you want to set the status as well, use Status(). keyvalues must be an even number with every even value a string representing the key, with the following value representing the value associated with that key. The following values are supported:

• bool/[]bool
• float64/[]float64
• int/[]int
• int64/[]int64
• string/[]string
• time.Duration/[]time.Duration

func (Span) Event

func (s Span) Event(name string, keyValues ...any) error

Event records an event with name and keyvalues. keyvalues must be an even number with every even value a string representing the key, with the following value representing the value associated with that key. The following values are supported:

• bool/[]bool
• float64/[]float64
• int/[]int
• int64/[]int64
• string/[]string
• time.Duration/[]time.Duration

func (Span) IsRecording

func (s Span) IsRecording() bool

IsRecording returns true if the span is recording events. This is safe to call even if the span is nil.

func (Span) Status

func (s Span) Status(code codes.Code, description string)

Status records a status for the span.