cloudflared-mirror/vendor/github.com/getsentry/sentry-go/tracing.go

777 lines
23 KiB
Go
Raw Permalink Normal View History

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...,
)
}