Skip to content

SigNoz is an open-source, OpenTelemetry-native observability platform for your team and their AI agents. Get logs, metrics, and traces in one tool with features like APM, distributed tracing, log management, infra monitoring, etc. Combined with SigNoz MCP and a native AI teammate (in SigNoz Cloud) it helps you build more resilient apps.

7.5 KB
Raw Blame
package spantypes

import (
	"encoding/base64"
	"encoding/json"
	"maps"

	"github.com/SigNoz/signoz/pkg/errors"
	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
)

const (
	threadDefaultLimit = 20
	threadMaxLimit     = 100
)

const (
	ThreadAfter  ThreadFrom = iota // > cursor, ascending
	ThreadAt                       // >= cursor, ascending
	ThreadBefore                   // < cursor, descending
)

var (
	ErrCodeThreadInvalidLimit  = errors.MustNewCode("trace_thread_invalid_limit")
	ErrCodeThreadInvalidCursor = errors.MustNewCode("trace_thread_invalid_cursor")
	ErrCodeThreadInvalidAnchor = errors.MustNewCode("trace_thread_invalid_anchor")
	ErrCodeThreadSpanNotFound  = errors.MustNewCode("trace_thread_span_not_found")
)

type GetTraceThreadParams struct {
	Limit  int    `query:"limit" description:"Page size, at most 100. 0 means 20."`
	After  string `query:"after" description:"The nextCursor of a page; returns the spans after it. Set only one of after, before and spanId."`
	Before string `query:"before" description:"The prevCursor of a page; returns the spans before it. Set only one of after, before and spanId."`
	SpanID string `query:"spanId" description:"Returns the page around this span. Set only one of after, before and spanId."`
}

type ThreadQuery struct {
	Limit  int
	After  *ThreadCursor
	Before *ThreadCursor
	SpanID string
}

// ThreadCursor is the (TimeUnixNano, SpanID) key of a span.
type ThreadCursor struct {
	TimeUnixNano uint64 `json:"timeUnixNano"`
	SpanID       string `json:"spanId"`
}

type ThreadFrom int

type ThreadPage struct {
	Cursor *ThreadCursor
	From   ThreadFrom
	Limit  int
}

type GettableTraceThread struct {
	Spans      []*ThreadSpan `json:"spans" required:"true" nullable:"false"`
	PrevCursor string        `json:"prevCursor,omitempty"`
	NextCursor string        `json:"nextCursor,omitempty"`
}

// ThreadSpan carries the fields the span details pane reads; snake_case keys match WaterfallSpan.
type ThreadSpan struct {
	SpanID           string            `json:"span_id" required:"true"`
	TraceID          string            `json:"trace_id" required:"true"`
	ParentSpanID     string            `json:"parent_span_id" required:"true"`
	Name             string            `json:"name" required:"true"`
	KindString       string            `json:"kind_string" required:"true"`
	TimeUnix         uint64            `json:"time_unix" required:"true"`
	DurationNano     uint64            `json:"duration_nano" required:"true"`
	HasError         bool              `json:"has_error" required:"true"`
	StatusCodeString string            `json:"status_code_string" required:"true"`
	StatusMessage    string            `json:"status_message" required:"true"`
	Resource         map[string]string `json:"resource" required:"true" nullable:"false"`
	Attributes       map[string]any    `json:"attributes" required:"true" nullable:"false"`
	Events           []Event           `json:"events" required:"true" nullable:"false"`
	References       []OtelSpanRef     `json:"references" required:"true" nullable:"false"`
	// The formatted fields hold the span's messages in the OTel GenAI shape; FormatterWarnings holds what
	// the converter could not resolve.
	FormattedInput    aiobservabilitytypes.InputMessages  `json:"formattedInput" required:"true" nullable:"false"`
	FormattedOutput   aiobservabilitytypes.OutputMessages `json:"formattedOutput" required:"true" nullable:"false"`
	FormatterWarnings []string                            `json:"formatterWarnings" required:"true" nullable:"false"`

	timeUnixNano uint64
}

func NewThreadQuery(params *GetTraceThreadParams) (*ThreadQuery, error) {
	query := &ThreadQuery{Limit: params.Limit, SpanID: params.SpanID}
	if query.Limit < 0 {
		return nil, errors.NewInvalidInputf(ErrCodeThreadInvalidLimit, "limit cannot be negative, got %d", query.Limit)
	}
	if query.Limit == 0 {
		query.Limit = threadDefaultLimit
	}
	if query.Limit > threadMaxLimit {
		return nil, errors.NewInvalidInputf(ErrCodeThreadInvalidLimit, "limit cannot exceed %d, got %d", threadMaxLimit, query.Limit)
	}

	anchors := 0
	for _, value := range []string{params.After, params.Before, params.SpanID} {
		if value != "" {
			anchors++
		}
	}
	if anchors > 1 {
		return nil, errors.NewInvalidInputf(ErrCodeThreadInvalidAnchor, "only one of after, before and spanId can be set")
	}

	encoded := params.After
	if encoded == "" {
		encoded = params.Before
	}
	if encoded == "" {
		return query, nil
	}
	data, err := base64.RawURLEncoding.DecodeString(encoded)
	if err != nil {
		return nil, errors.WrapInvalidInputf(err, ErrCodeThreadInvalidCursor, "invalid cursor")
	}
	cursor := new(ThreadCursor)
	if err := json.Unmarshal(data, cursor); err != nil {
		return nil, errors.WrapInvalidInputf(err, ErrCodeThreadInvalidCursor, "invalid cursor")
	}
	if cursor.SpanID == "" {
		return nil, errors.NewInvalidInputf(ErrCodeThreadInvalidCursor, "invalid cursor: missing span id")
	}
	if params.After != "" {
		query.After = cursor
	} else {
		query.Before = cursor
	}
	return query, nil
}

func (c ThreadCursor) Encode() string {
	data, _ := json.Marshal(c)
	return base64.RawURLEncoding.EncodeToString(data)
}

// NewGettableTraceThread takes up to limit+1 spans on each side of the anchor: before in
// descending order, after in ascending order. Half the page goes to before, the rest to after,
// and a short side gives its room to the other. An extra span on a side sets that side's cursor.
func NewGettableTraceThread(traceID string, query *ThreadQuery, before, after []StorableSpan) *GettableTraceThread {
	nAfter := min(len(after), query.Limit-min(len(before), query.Limit/2))
	nBefore := min(len(before), query.Limit-nAfter)
	hasPrev := len(before) > nBefore || query.After != nil
	hasNext := len(after) > nAfter || query.Before != nil

	spans := make([]*ThreadSpan, 0, nBefore+nAfter)
	for i := nBefore - 1; i >= 0; i-- {
		spans = append(spans, newThreadSpan(traceID, &before[i]))
	}
	for i := range nAfter {
		spans = append(spans, newThreadSpan(traceID, &after[i]))
	}

	thread := &GettableTraceThread{Spans: spans}
	if len(spans) == 0 {
		return thread
	}
	if hasPrev {
		thread.PrevCursor = spans[0].cursor().Encode()
	}
	if hasNext {
		thread.NextCursor = spans[len(spans)-1].cursor().Encode()
	}
	return thread
}

func (s *ThreadSpan) cursor() ThreadCursor {
	return ThreadCursor{TimeUnixNano: s.timeUnixNano, SpanID: s.SpanID}
}

func newThreadSpan(traceID string, storable *StorableSpan) *ThreadSpan {
	resources := make(map[string]string, len(storable.ResourcesString))
	maps.Copy(resources, storable.ResourcesString)
	timeUnixNano := uint64(storable.StartTime.UnixNano())
	attributes := storable.Attributes()
	// Spans from before the JSON rollout have an empty document and format to nothing.
	formatted := aiobservabilitytypes.FormatMessages(storable.AttributesJSON.Nest())
	return &ThreadSpan{
		SpanID:            storable.SpanID,
		TraceID:           traceID,
		ParentSpanID:      storable.ParentSpanID,
		Name:              storable.Name,
		KindString:        storable.SpanKind,
		TimeUnix:          timeUnixNano / 1_000_000, // client expects millis, as in the waterfall
		DurationNano:      storable.DurationNano,
		HasError:          storable.HasError,
		StatusCodeString:  storable.StatusCodeString,
		StatusMessage:     storable.StatusMessage,
		Resource:          resources,
		Attributes:        attributes,
		Events:            storable.UnmarshalledEvents(),
		References:        storable.UnmarshalledRefs(),
		FormattedInput:    formatted.Input,
		FormattedOutput:   formatted.Output,
		FormatterWarnings: formatted.Warnings,
		timeUnixNano:      timeUnixNano,
	}
}