tracing

Documentation

Overview

Package tracing defines tracing APIs to be used by Smithy clients.

Index

• func WithOperationTracer(parent context.Context, tracer Tracer) context.Context
• func WithSpan(parent context.Context, span Span) context.Context
• type EventOption
• type EventOptions
• type NopTracerProvider
  • func (NopTracerProvider) Tracer(string, ...TracerOption) Tracer
• type Span
  • func GetSpan(ctx context.Context) (Span, bool)
  • func PopSpan(parent context.Context) (context.Context, Span)
  • func StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)
• type SpanContext
  • func (ctx *SpanContext) IsValid() bool
• type SpanKind
• type SpanOption
• type SpanOptions
• type SpanStatus
• type Tracer
  • func GetOperationTracer(ctx context.Context) (Tracer, bool)
• type TracerOption
• type TracerOptions
• type TracerProvider

Functions

func WithOperationTracer

func WithOperationTracer(parent context.Context, tracer Tracer) context.Context

WithOperationTracer returns a child Context embedding the given Tracer.

The runtime will use this embed a scoped tracer for client operations, Smithy/SDK client callers DO NOT need to do this explicitly.

func WithSpan

func WithSpan(parent context.Context, span Span) context.Context

WithSpan sets the active trace Span on the context.

Types

type EventOption

type EventOption func(o *EventOptions)

EventOption applies configuration to a span event.

type EventOptions

type EventOptions struct {
	Properties smithy.Properties
}

EventOptions represent configuration for span events.

type NopTracerProvider

type NopTracerProvider struct{}

NopTracerProvider is a no-op tracing implementation.

func (NopTracerProvider) Tracer

func (NopTracerProvider) Tracer(string, ...TracerOption) Tracer

Tracer returns a tracer which creates no-op spans.

type Span

type Span interface {
	Name() string
	Context() SpanContext
	AddEvent(name string, opts ...EventOption)
	SetStatus(status SpanStatus)
	SetProperty(k, v any)
	End()
}

Span records a conceptually individual unit of work that takes place in a Smithy client operation.

func GetSpan

func GetSpan(ctx context.Context) (Span, bool)

GetSpan returns the active trace Span on the context.

The boolean in the return indicates whether a Span was actually in the context, but a no-op implementation will be returned if not, so callers can generally disregard the boolean unless they wish to explicitly confirm presence/absence of a Span.

func PopSpan

func PopSpan(parent context.Context) (context.Context, Span)

PopSpan pops the current Span off the context, setting the active Span on the returned Context back to its parent and returning the REMOVED one.

PopSpan on a context with no active Span will return a no-op instance.

This is mostly necessary for the runtime to manage base trace spans due to the wrapped-function nature of the middleware stack. End-users of Smithy clients SHOULD NOT generally be using this API.

func StartSpan

func StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

StartSpan is a convenience API for creating tracing Spans from a Context.

StartSpan uses the operation-scoped Tracer, previously stored using WithOperationTracer, to start the Span. If a Tracer has not been embedded the returned Span will be a no-op implementation.

type SpanContext

type SpanContext struct {
	TraceID  string
	SpanID   string
	IsRemote bool
}

SpanContext uniquely identifies a Span.

func (*SpanContext) IsValid

func (ctx *SpanContext) IsValid() bool

IsValid is true when a span has nonzero trace and span IDs.

type SpanKind

type SpanKind int

SpanKind indicates the nature of the work being performed.

const (
	SpanKindInternal SpanKind = iota
	SpanKindClient
	SpanKindServer
	SpanKindProducer
	SpanKindConsumer
)

Enumeration of SpanKind.

type SpanOption

type SpanOption func(o *SpanOptions)

SpanOption applies configuration to a span.

type SpanOptions

type SpanOptions struct {
	Kind       SpanKind
	Properties smithy.Properties
}

SpanOptions represent configuration for span events.

type SpanStatus

type SpanStatus int

SpanStatus records the "success" state of an observed span.

const (
	SpanStatusUnset SpanStatus = iota
	SpanStatusOK
	SpanStatusError
)

Enumeration of SpanStatus.

type Tracer

type Tracer interface {
	StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)
}

Tracer is the entry point for creating observed client Spans.

Spans created by tracers propagate by existing on the Context. Consumers of the API can use GetSpan to pull the active Span from a Context.

Creation of child Spans is implicit through Context persistence. If CreateSpan is called with a Context that holds a Span, the result will be a child of that Span.

func GetOperationTracer

func GetOperationTracer(ctx context.Context) (Tracer, bool)

GetOperationTracer returns the embedded operation-scoped Tracer on a Context.

The boolean in the return indicates whether a Tracer was actually in the context, but a no-op implementation will be returned if not, so callers can generally disregard the boolean unless they wish to explicitly confirm presence/absence of a Tracer.

type TracerOption

type TracerOption func(o *TracerOptions)

TracerOption applies configuration to a tracer.

type TracerOptions

type TracerOptions struct {
	Properties smithy.Properties
}

TracerOptions represent configuration for tracers.

type TracerProvider

type TracerProvider interface {
	Tracer(scope string, opts ...TracerOption) Tracer
}

TracerProvider is the entry point for creating client traces.