Documentation
¶
Overview ¶
Package span provides methods to create new spans and get existing spans. This can be used to provide tracing for a service. This package is a wrapper around the OpenTelemetry Go SDK.
The general use looks like:
func someFunction(ctx context.Context) error {
// This creates a new span inside a trace. If the trace is not recording, the span is a noop.
// The span is created with a span kind of internal, unless another span kind is passed using
// the WithSpanKind() option. The name of the span will be the name of the function. The span
// includes attributes for the file name and line number. You can override the span name by
// using the WithName() option. Timings for the span are automatically recorded by the OTEL
// library.
ctx, span := span.New(ctx)
// This will automatically record the span status of Ok if span.Status() or errors.E() has not been
// called.
defer span.End()
...
// If you want to record an event within the span, you can simply do:
span.Event("event name", attribute.String("key", "value"), attribute.Int("key", 1))
...
}
If you want to use an existing span, you can use span.Get(ctx) this usually looks like:
func someFunction(ctx context.Context) error {
span := span.Get(ctx)
...
span.Event("event name", attribute.String("key", "value"), attribute.Int("key", 1))
...
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Attributes ¶
type Attributes struct {
// Attrs is the list of attributes to be added to the span.
Attrs []attribute.KeyValue
// contains filtered or unexported fields
}
Attributes is a helper collect attributes for a span. If an error is encountered while adding attributes, the error will be stored and no more attributes will be added. The error can be retrieved by calling Err().
func (*Attributes) Add ¶
func (a *Attributes) Add(kv attribute.KeyValue)
Add adds a key value pair to the Attributes. If the key is already present, the value wil added to the attribute list and OTEL package will determine how to handle it.
func (*Attributes) Err ¶
func (a *Attributes) Err() error
Err returns the error that was set on the Attributes during the Add() method.
type Option ¶
type Option func(spanOpts) (spanOpts, error)
Option is an option to New().
func WithName ¶
WithName overrides the default span name with the provided name. The name is limited to 255 characters. If the name is longer than 255 characters, it will be truncated.
func WithSpanEndOption ¶
func WithSpanEndOption(options ...trace.SpanEndOption) Option
WithSpanEndOption adds trace.SpanEndOption(s) to the span end.
func WithSpanStartOption ¶
func WithSpanStartOption(options ...trace.SpanStartOption) Option
WithSpanStartOption adds trace.SpanStartOption(s) to the span creation.
type Span ¶
type Span struct {
// Span is the OTEL trace.Span.
Span trace.Span
// contains filtered or unexported fields
}
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 as an attribute for other needs.
func Get ¶
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. Only use this if you want to write to an existing span. Most times, you will want to use New() to create a new child span.
func New ¶
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. If you pass a nil Context, this will return the background Context with a noop span. If an option is passed that is not valid, it is ignored and an error is logged. The span is created with a span kind of internal, unless another span kind is passed using WithSpanStartOption(WithSpanKind([kind])). This starts the span.
func (Span) End ¶
func (s Span) End()
End ends the span. If the status hasn't been set by either calling .Status() or using errors.E(), then the status is set to OK. If the span is not recording, this is a no-op.
func (Span) Event ¶
Event records an event with name and KeyValue. You can create KeyValue(s) using the attribute package, like attribute.String("key", "value"). If the span is not recording, this is a noop.
func (Span) IsRecording ¶
IsRecording returns true if the span is recording events. This is safe to call even if the span is nil.
Source Files