package sentry import ( "context" "crypto/rand" "encoding/hex" "encoding/json" "fmt" "net/http" "regexp" "strings" "time" ) // A Span is the building block of a Sentry transaction. Spans build up a tree // structure of timed operations. The span tree makes up a transaction event // that is sent to Sentry when the root span is finished. // // Spans must be started with either StartSpan or Span.StartChild. type Span struct { //nolint: maligned // prefer readability over optimal memory layout (see note below *) TraceID TraceID `json:"trace_id"` SpanID SpanID `json:"span_id"` ParentSpanID SpanID `json:"parent_span_id"` Op string `json:"op,omitempty"` Description string `json:"description,omitempty"` Status SpanStatus `json:"status,omitempty"` Tags map[string]string `json:"tags,omitempty"` StartTime time.Time `json:"start_timestamp"` EndTime time.Time `json:"timestamp"` Data map[string]interface{} `json:"data,omitempty"` Sampled Sampled `json:"-"` Source TransactionSource `json:"-"` // sample rate the span was sampled with. sampleRate float64 // ctx is the context where the span was started. Always non-nil. ctx context.Context // Dynamic Sampling context dynamicSamplingContext DynamicSamplingContext // parent refers to the immediate local parent span. A remote parent span is // only referenced by setting ParentSpanID. parent *Span // isTransaction is true only for the root span of a local span tree. The // root span is the first span started in a context. Note that a local root // span may have a remote parent belonging to the same trace, therefore // isTransaction depends on ctx and not on parent. isTransaction bool // recorder stores all spans in a transaction. Guaranteed to be non-nil. recorder *spanRecorder } // (*) Note on maligned: // // We prefer readability over optimal memory layout. If we ever decide to // reorder fields, we can use a tool: // // go run honnef.co/go/tools/cmd/structlayout -json . Span | go run honnef.co/go/tools/cmd/structlayout-optimize // // Other structs would deserve reordering as well, for example Event. // TODO: make Span.Tags and Span.Data opaque types (struct{unexported []slice}). // An opaque type allows us to add methods and make it more convenient to use // than maps, because maps require careful nil checks to use properly or rely on // explicit initialization for every span, even when there might be no // tags/data. For Span.Data, must gracefully handle values that cannot be // marshaled into JSON (see transport.go:getRequestBodyFromEvent). // StartSpan starts a new span to describe an operation. The new span will be a // child of the last span stored in ctx, if any. // // One or more options can be used to modify the span properties. Typically one // option as a function literal is enough. Combining multiple options can be // useful to define and reuse specific properties with named functions. // // Caller should call the Finish method on the span to mark its end. Finishing a // root span sends the span and all of its children, recursively, as a // transaction to Sentry. func StartSpan(ctx context.Context, operation string, options ...SpanOption) *Span { parent, hasParent := ctx.Value(spanContextKey{}).(*Span) var span Span span = Span{ // defaults Op: operation, StartTime: time.Now(), Sampled: SampledUndefined, ctx: context.WithValue(ctx, spanContextKey{}, &span), parent: parent, isTransaction: !hasParent, } if hasParent { span.TraceID = parent.TraceID } else { // Only set the Source if this is a transaction span.Source = SourceCustom // Implementation note: // // While math/rand is ~2x faster than crypto/rand (exact // difference depends on hardware / OS), crypto/rand is probably // fast enough and a safer choice. // // For reference, OpenTelemetry [1] uses crypto/rand to seed // math/rand. AFAICT this approach does not preserve the // properties from crypto/rand that make it suitable for // cryptography. While it might be debatable whether those // properties are important for us here, again, we're taking the // safer path. // // See [2a] & [2b] for a discussion of some of the properties we // obtain by using crypto/rand and [3a] & [3b] for why we avoid // math/rand. // // Because the math/rand seed has only 64 bits (int64), if the // first thing we do after seeding an RNG is to read in a random // TraceID, there are only 2^64 possible values. Compared to // UUID v4 that have 122 random bits, there is a much greater // chance of collision [4a] & [4b]. // // [1]: https://github.com/open-telemetry/opentelemetry-go/blob/958041ddf619a128/sdk/trace/trace.go#L25-L31 // [2a]: https://security.stackexchange.com/q/120352/246345 // [2b]: https://security.stackexchange.com/a/120365/246345 // [3a]: https://github.com/golang/go/issues/11871#issuecomment-126333686 // [3b]: https://github.com/golang/go/issues/11871#issuecomment-126357889 // [4a]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Collisions // [4b]: https://www.wolframalpha.com/input/?i=sqrt%282*2%5E64*ln%281%2F%281-0.5%29%29%29 _, err := rand.Read(span.TraceID[:]) if err != nil { panic(err) } } _, err := rand.Read(span.SpanID[:]) if err != nil { panic(err) } if hasParent { span.ParentSpanID = parent.SpanID } // Apply options to override defaults. for _, option := range options { option(&span) } span.Sampled = span.sample() if hasParent { span.recorder = parent.spanRecorder() } else { span.recorder = &spanRecorder{} } span.recorder.record(&span) // Update scope so that all events include a trace context, allowing // Sentry to correlate errors to transactions/spans. hubFromContext(ctx).Scope().SetContext("trace", span.traceContext().Map()) return &span } // Finish sets the span's end time, unless already set. If the span is the root // of a span tree, Finish sends the span tree to Sentry as a transaction. func (s *Span) Finish() { // TODO(tracing): maybe make Finish run at most once, such that // (incorrectly) calling it twice never double sends to Sentry. if s.EndTime.IsZero() { s.EndTime = monotonicTimeSince(s.StartTime) } if !s.Sampled.Bool() { return } event := s.toEvent() if event == nil { return } // TODO(tracing): add breadcrumbs // (see https://github.com/getsentry/sentry-python/blob/f6f3525f8812f609/sentry_sdk/tracing.py#L372) hub := hubFromContext(s.ctx) if hub.Scope().Transaction() == "" { Logger.Printf("Missing transaction name for span with op = %q", s.Op) } hub.CaptureEvent(event) } // Context returns the context containing the span. func (s *Span) Context() context.Context { return s.ctx } // StartChild starts a new child span. // // The call span.StartChild(operation, options...) is a shortcut for // StartSpan(span.Context(), operation, options...). func (s *Span) StartChild(operation string, options ...SpanOption) *Span { return StartSpan(s.Context(), operation, options...) } // SetTag sets a tag on the span. It is recommended to use SetTag instead of // accessing the tags map directly as SetTag takes care of initializing the map // when necessary. func (s *Span) SetTag(name, value string) { if s.Tags == nil { s.Tags = make(map[string]string) } s.Tags[name] = value } // TODO(tracing): maybe add shortcuts to get/set transaction name. Right now the // transaction name is in the Scope, as it has existed there historically, prior // to tracing. // // See Scope.Transaction() and Scope.SetTransaction(). // // func (s *Span) TransactionName() string // func (s *Span) SetTransactionName(name string) // ToSentryTrace returns the trace propagation value used with the sentry-trace // HTTP header. func (s *Span) ToSentryTrace() string { // TODO(tracing): add instrumentation for outgoing HTTP requests using // ToSentryTrace. var b strings.Builder fmt.Fprintf(&b, "%s-%s", s.TraceID.Hex(), s.SpanID.Hex()) switch s.Sampled { case SampledTrue: b.WriteString("-1") case SampledFalse: b.WriteString("-0") } return b.String() } func (s *Span) ToBaggage() string { return s.dynamicSamplingContext.String() } // sentryTracePattern matches either // // TRACE_ID - SPAN_ID // [[:xdigit:]]{32}-[[:xdigit:]]{16} // // or // // TRACE_ID - SPAN_ID - SAMPLED // [[:xdigit:]]{32}-[[:xdigit:]]{16}-[01] var sentryTracePattern = regexp.MustCompile(`^([[:xdigit:]]{32})-([[:xdigit:]]{16})(?:-([01]))?$`) // updateFromSentryTrace parses a sentry-trace HTTP header (as returned by // ToSentryTrace) and updates fields of the span. If the header cannot be // recognized as valid, the span is left unchanged. func (s *Span) updateFromSentryTrace(header []byte) { m := sentryTracePattern.FindSubmatch(header) if m == nil { // no match return } _, _ = hex.Decode(s.TraceID[:], m[1]) _, _ = hex.Decode(s.ParentSpanID[:], m[2]) if len(m[3]) != 0 { switch m[3][0] { case '0': s.Sampled = SampledFalse case '1': s.Sampled = SampledTrue } } } func (s *Span) updateFromBaggage(header []byte) { if s.isTransaction { dsc, err := DynamicSamplingContextFromHeader(header) if err != nil { return } s.dynamicSamplingContext = dsc } } func (s *Span) MarshalJSON() ([]byte, error) { // span aliases Span to allow calling json.Marshal without an infinite loop. // It preserves all fields while none of the attached methods. type span Span var parentSpanID string if s.ParentSpanID != zeroSpanID { parentSpanID = s.ParentSpanID.String() } return json.Marshal(struct { *span ParentSpanID string `json:"parent_span_id,omitempty"` }{ span: (*span)(s), ParentSpanID: parentSpanID, }) } func (s *Span) sample() Sampled { hub := hubFromContext(s.ctx) var clientOptions ClientOptions client := hub.Client() if client != nil { clientOptions = hub.Client().Options() } // https://develop.sentry.dev/sdk/performance/#sampling // #1 tracing is not enabled. if !clientOptions.EnableTracing { Logger.Printf("Dropping transaction: EnableTracing is set to %t", clientOptions.EnableTracing) s.sampleRate = 0.0 return SampledFalse } // #2 explicit sampling decision via StartSpan/StartTransaction options. if s.Sampled != SampledUndefined { Logger.Printf("Using explicit sampling decision from StartSpan/StartTransaction: %v", s.Sampled) switch s.Sampled { case SampledTrue: s.sampleRate = 1.0 case SampledFalse: s.sampleRate = 0.0 } return s.Sampled } // Variant for non-transaction spans: they inherit the parent decision. // Note: non-transaction should always have a parent, but we check both // conditions anyway -- the first for semantic meaning, the second to // avoid a nil pointer dereference. if !s.isTransaction && s.parent != nil { return s.parent.Sampled } // #3 use TracesSampler from ClientOptions. sampler := clientOptions.TracesSampler samplingContext := SamplingContext{Span: s, Parent: s.parent} if sampler != nil { tracesSamplerSampleRate := sampler.Sample(samplingContext) s.sampleRate = tracesSamplerSampleRate if tracesSamplerSampleRate < 0.0 || tracesSamplerSampleRate > 1.0 { Logger.Printf("Dropping transaction: Returned TracesSampler rate is out of range [0.0, 1.0]: %f", tracesSamplerSampleRate) return SampledFalse } if tracesSamplerSampleRate == 0 { Logger.Printf("Dropping transaction: Returned TracesSampler rate is: %f", tracesSamplerSampleRate) return SampledFalse } if rng.Float64() < tracesSamplerSampleRate { return SampledTrue } Logger.Printf("Dropping transaction: TracesSampler returned rate: %f", tracesSamplerSampleRate) return SampledFalse } // #4 inherit parent decision. if s.parent != nil { Logger.Printf("Using sampling decision from parent: %v", s.parent.Sampled) switch s.parent.Sampled { case SampledTrue: s.sampleRate = 1.0 case SampledFalse: s.sampleRate = 0.0 } return s.parent.Sampled } // #5 use TracesSampleRate from ClientOptions. sampleRate := clientOptions.TracesSampleRate s.sampleRate = sampleRate if sampleRate < 0.0 || sampleRate > 1.0 { Logger.Printf("Dropping transaction: TracesSamplerRate out of range [0.0, 1.0]: %f", sampleRate) return SampledFalse } if sampleRate == 0.0 { Logger.Printf("Dropping transaction: TracesSampleRate rate is: %f", sampleRate) return SampledFalse } if rng.Float64() < sampleRate { return SampledTrue } return SampledFalse } func (s *Span) toEvent() *Event { if !s.isTransaction { return nil // only transactions can be transformed into events } hub := hubFromContext(s.ctx) children := s.recorder.children() finished := make([]*Span, 0, len(children)) for _, child := range children { if child.EndTime.IsZero() { Logger.Printf("Dropped unfinished span: Op=%q TraceID=%s SpanID=%s", child.Op, child.TraceID, child.SpanID) continue } finished = append(finished, child) } // Create and attach a DynamicSamplingContext to the transaction. // If the DynamicSamplingContext is not frozen at this point, we can assume being head of trace. if !s.dynamicSamplingContext.IsFrozen() { s.dynamicSamplingContext = DynamicSamplingContextFromTransaction(s) } return &Event{ Type: transactionType, Transaction: hub.Scope().Transaction(), Contexts: map[string]Context{ "trace": s.traceContext().Map(), }, Tags: s.Tags, Extra: s.Data, Timestamp: s.EndTime, StartTime: s.StartTime, Spans: finished, TransactionInfo: &TransactionInfo{ Source: s.Source, }, sdkMetaData: SDKMetaData{ dsc: s.dynamicSamplingContext, }, } } func (s *Span) traceContext() *TraceContext { return &TraceContext{ TraceID: s.TraceID, SpanID: s.SpanID, ParentSpanID: s.ParentSpanID, Op: s.Op, Description: s.Description, Status: s.Status, } } // spanRecorder stores the span tree. Guaranteed to be non-nil. func (s *Span) spanRecorder() *spanRecorder { return s.recorder } // TraceID identifies a trace. type TraceID [16]byte func (id TraceID) Hex() []byte { b := make([]byte, hex.EncodedLen(len(id))) hex.Encode(b, id[:]) return b } func (id TraceID) String() string { return string(id.Hex()) } func (id TraceID) MarshalText() ([]byte, error) { return id.Hex(), nil } // SpanID identifies a span. type SpanID [8]byte func (id SpanID) Hex() []byte { b := make([]byte, hex.EncodedLen(len(id))) hex.Encode(b, id[:]) return b } func (id SpanID) String() string { return string(id.Hex()) } func (id SpanID) MarshalText() ([]byte, error) { return id.Hex(), nil } // Zero values of TraceID and SpanID used for comparisons. var ( zeroTraceID TraceID zeroSpanID SpanID ) // Contains information about how the name of the transaction was determined. type TransactionSource string const ( SourceCustom TransactionSource = "custom" SourceURL TransactionSource = "url" SourceRoute TransactionSource = "route" SourceView TransactionSource = "view" SourceComponent TransactionSource = "component" SourceTask TransactionSource = "task" ) // SpanStatus is the status of a span. type SpanStatus uint8 // Implementation note: // // In Relay (ingestion), the SpanStatus type is an enum used as // Annotated<SpanStatus> when embedded in structs, making it effectively // Option<SpanStatus>. It means the status is either null or one of the known // string values. // // In Snuba (search), the SpanStatus is stored as an uint8 and defaulted to 2 // ("unknown") when not set. It means that Discover searches for // `transaction.status:unknown` return both transactions/spans with status // `null` or `"unknown"`. Searches for `transaction.status:""` return nothing. // // With that in mind, the Go SDK default is SpanStatusUndefined, which is // null/omitted when serializing to JSON, but integrations may update the status // automatically based on contextual information. const ( SpanStatusUndefined SpanStatus = iota SpanStatusOK SpanStatusCanceled SpanStatusUnknown SpanStatusInvalidArgument SpanStatusDeadlineExceeded SpanStatusNotFound SpanStatusAlreadyExists SpanStatusPermissionDenied SpanStatusResourceExhausted SpanStatusFailedPrecondition SpanStatusAborted SpanStatusOutOfRange SpanStatusUnimplemented SpanStatusInternalError SpanStatusUnavailable SpanStatusDataLoss SpanStatusUnauthenticated maxSpanStatus ) func (ss SpanStatus) String() string { if ss >= maxSpanStatus { return "" } m := [maxSpanStatus]string{ "", "ok", "cancelled", // [sic] "unknown", "invalid_argument", "deadline_exceeded", "not_found", "already_exists", "permission_denied", "resource_exhausted", "failed_precondition", "aborted", "out_of_range", "unimplemented", "internal_error", "unavailable", "data_loss", "unauthenticated", } return m[ss] } func (ss SpanStatus) MarshalJSON() ([]byte, error) { s := ss.String() if s == "" { return []byte("null"), nil } return json.Marshal(s) } // A TraceContext carries information about an ongoing trace and is meant to be // stored in Event.Contexts (as *TraceContext). type TraceContext struct { TraceID TraceID `json:"trace_id"` SpanID SpanID `json:"span_id"` ParentSpanID SpanID `json:"parent_span_id"` Op string `json:"op,omitempty"` Description string `json:"description,omitempty"` Status SpanStatus `json:"status,omitempty"` } func (tc *TraceContext) MarshalJSON() ([]byte, error) { // traceContext aliases TraceContext to allow calling json.Marshal without // an infinite loop. It preserves all fields while none of the attached // methods. type traceContext TraceContext var parentSpanID string if tc.ParentSpanID != zeroSpanID { parentSpanID = tc.ParentSpanID.String() } return json.Marshal(struct { *traceContext ParentSpanID string `json:"parent_span_id,omitempty"` }{ traceContext: (*traceContext)(tc), ParentSpanID: parentSpanID, }) } func (tc TraceContext) Map() map[string]interface{} { m := map[string]interface{}{ "trace_id": tc.TraceID, "span_id": tc.SpanID, } if tc.ParentSpanID != [8]byte{} { m["parent_span_id"] = tc.ParentSpanID } if tc.Op != "" { m["op"] = tc.Op } if tc.Description != "" { m["description"] = tc.Description } if tc.Status > 0 && tc.Status < maxSpanStatus { m["status"] = tc.Status } return m } // Sampled signifies a sampling decision. type Sampled int8 // The possible trace sampling decisions are: SampledFalse, SampledUndefined // (default) and SampledTrue. const ( SampledFalse Sampled = -1 SampledUndefined Sampled = 0 SampledTrue Sampled = 1 ) func (s Sampled) String() string { switch s { case SampledFalse: return "SampledFalse" case SampledUndefined: return "SampledUndefined" case SampledTrue: return "SampledTrue" default: return fmt.Sprintf("SampledInvalid(%d)", s) } } // Bool returns true if the sample decision is SampledTrue, false otherwise. func (s Sampled) Bool() bool { return s == SampledTrue } // A SpanOption is a function that can modify the properties of a span. type SpanOption func(s *Span) // The TransactionName option sets the name of the current transaction. // // A span tree has a single transaction name, therefore using this option when // starting a span affects the span tree as a whole, potentially overwriting a // name set previously. func TransactionName(name string) SpanOption { return func(s *Span) { hubFromContext(s.Context()).Scope().SetTransaction(name) } } // OpName sets the operation name for a given span. func OpName(name string) SpanOption { return func(s *Span) { s.Op = name } } // TransctionSource sets the source of the transaction name. func TransctionSource(source TransactionSource) SpanOption { return func(s *Span) { s.Source = source } } // ContinueFromRequest returns a span option that updates the span to continue // an existing trace. If it cannot detect an existing trace in the request, the // span will be left unchanged. // // ContinueFromRequest is an alias for: // // ContinueFromHeaders(r.Header.Get("sentry-trace"), r.Header.Get("baggage")). func ContinueFromRequest(r *http.Request) SpanOption { return ContinueFromHeaders(r.Header.Get("sentry-trace"), r.Header.Get("baggage")) } // ContinueFromHeaders returns a span option that updates the span to continue // an existing TraceID and propagates the Dynamic Sampling context. func ContinueFromHeaders(trace, baggage string) SpanOption { return func(s *Span) { if trace != "" { s.updateFromSentryTrace([]byte(trace)) } if baggage != "" { s.updateFromBaggage([]byte(baggage)) } // In case a sentry-trace header is present but no baggage header, // create an empty, frozen DynamicSamplingContext. if trace != "" && baggage == "" { s.dynamicSamplingContext = DynamicSamplingContext{ Frozen: true, } } } } // ContinueFromTrace returns a span option that updates the span to continue // an existing TraceID. func ContinueFromTrace(trace string) SpanOption { return func(s *Span) { if trace == "" { return } s.updateFromSentryTrace([]byte(trace)) } } // spanContextKey is used to store span values in contexts. type spanContextKey struct{} // TransactionFromContext returns the root span of the current transaction. It // returns nil if no transaction is tracked in the context. func TransactionFromContext(ctx context.Context) *Span { if span, ok := ctx.Value(spanContextKey{}).(*Span); ok { return span.recorder.root() } return nil } // spanFromContext returns the last span stored in the context or a dummy // non-nil span. // // TODO(tracing): consider exporting this. Without this, users cannot retrieve a // span from a context since spanContextKey is not exported. // // This can be added retroactively, and in the meantime think better whether it // should return nil (like GetHubFromContext), always non-nil (like // HubFromContext), or both: two exported functions. // // Note the equivalence: // // SpanFromContext(ctx).StartChild(...) === StartSpan(ctx, ...) // // So we don't aim spanFromContext at creating spans, but mutating existing // spans that you'd have no access otherwise (because it was created in code you // do not control, for example SDK auto-instrumentation). // // For now we provide TransactionFromContext, which solves the more common case // of setting tags, etc, on the current transaction. func spanFromContext(ctx context.Context) *Span { if span, ok := ctx.Value(spanContextKey{}).(*Span); ok { return span } return nil } // StartTransaction will create a transaction (root span) if there's no existing // transaction in the context otherwise, it will return the existing transaction. func StartTransaction(ctx context.Context, name string, options ...SpanOption) *Span { currentTransaction, exists := ctx.Value(spanContextKey{}).(*Span) if exists { return currentTransaction } options = append(options, TransactionName(name)) return StartSpan( ctx, "", options..., ) }