src

Go monorepo.
git clone git://code.dwrz.net/src
Log | Files | Refs

tracing.go (2404B)

      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 }