tracing.go raw

   1  // Package tracing defines tracing APIs to be used by Smithy clients.
   2  package tracing
   3  
   4  import (
   5  	"context"
   6  
   7  	"github.com/aws/smithy-go"
   8  )
   9  
  10  // SpanStatus records the "success" state of an observed span.
  11  type SpanStatus int
  12  
  13  // Enumeration of SpanStatus.
  14  const (
  15  	SpanStatusUnset SpanStatus = iota
  16  	SpanStatusOK
  17  	SpanStatusError
  18  )
  19  
  20  // SpanKind indicates the nature of the work being performed.
  21  type SpanKind int
  22  
  23  // Enumeration of SpanKind.
  24  const (
  25  	SpanKindInternal SpanKind = iota
  26  	SpanKindClient
  27  	SpanKindServer
  28  	SpanKindProducer
  29  	SpanKindConsumer
  30  )
  31  
  32  // TracerProvider is the entry point for creating client traces.
  33  type TracerProvider interface {
  34  	Tracer(scope string, opts ...TracerOption) Tracer
  35  }
  36  
  37  // TracerOption applies configuration to a tracer.
  38  type TracerOption func(o *TracerOptions)
  39  
  40  // TracerOptions represent configuration for tracers.
  41  type TracerOptions struct {
  42  	Properties smithy.Properties
  43  }
  44  
  45  // Tracer is the entry point for creating observed client Spans.
  46  //
  47  // Spans created by tracers propagate by existing on the Context. Consumers of
  48  // the API can use [GetSpan] to pull the active Span from a Context.
  49  //
  50  // Creation of child Spans is implicit through Context persistence. If
  51  // CreateSpan is called with a Context that holds a Span, the result will be a
  52  // child of that Span.
  53  type Tracer interface {
  54  	StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)
  55  }
  56  
  57  // SpanOption applies configuration to a span.
  58  type SpanOption func(o *SpanOptions)
  59  
  60  // SpanOptions represent configuration for span events.
  61  type SpanOptions struct {
  62  	Kind       SpanKind
  63  	Properties smithy.Properties
  64  }
  65  
  66  // Span records a conceptually individual unit of work that takes place in a
  67  // Smithy client operation.
  68  type Span interface {
  69  	Name() string
  70  	Context() SpanContext
  71  	AddEvent(name string, opts ...EventOption)
  72  	SetStatus(status SpanStatus)
  73  	SetProperty(k, v any)
  74  	End()
  75  }
  76  
  77  // EventOption applies configuration to a span event.
  78  type EventOption func(o *EventOptions)
  79  
  80  // EventOptions represent configuration for span events.
  81  type EventOptions struct {
  82  	Properties smithy.Properties
  83  }
  84  
  85  // SpanContext uniquely identifies a Span.
  86  type SpanContext struct {
  87  	TraceID  string
  88  	SpanID   string
  89  	IsRemote bool
  90  }
  91  
  92  // IsValid is true when a span has nonzero trace and span IDs.
  93  func (ctx *SpanContext) IsValid() bool {
  94  	return len(ctx.TraceID) != 0 && len(ctx.SpanID) != 0
  95  }
  96