trace

package
v1.80.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 3, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package trace captures request-lifecycle events (start, end, downstream calls, logs) into an in-memory ring buffer and fans them out to subscribers such as the dashboard. It is the data plane under /__nexus/events.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CleanStack added in v0.21.28

func CleanStack(raw string) string

CleanStack trims the runtime + recovery noise from a debug.Stack() output so the user-code frame ends up at the top.

Raw debug.Stack() looks like:

goroutine 25 [running]:
runtime/debug.Stack()
    .../runtime/debug/stack.go:26 +0x64
github.com/.../metrics.ginRecorder.func2.1()
    .../metrics/middleware.go:62 +0x148
panic({0x...})
    .../runtime/panic.go:860 +0x12c
github.com/.../users.NewBoom(...)            ← actual panic site
    .../examples/microsplit/users/handlers.go:66 +0x28
...

The first three frames (Stack itself, the deferred recover, panic) are framework noise — they shift on every Go release and tell the user nothing about their bug. We strip everything up to and including the panic frame so the cleaned stack starts at the user code. Returns the input unchanged when no `panic(` line is found (defensive — keeps the dashboard usable on edge-case inputs).

func HTTPClient added in v0.8.0

func HTTPClient(inner *http.Client) *http.Client

HTTPClient wraps an *http.Client so every outbound request auto-injects a traceparent header derived from the ctx on the request. Use it to stitch a trace across service boundaries:

client := trace.HTTPClient(nil) // or trace.HTTPClient(&myClient)
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
resp, err := client.Do(req)

If the request already has a traceparent set (e.g. because the caller injected one manually), it's left alone.

func In added in v0.8.0

func In(ctx context.Context, name string, attrs ...Attr) func(*error)

In is the common-case sugar for a one-call span. It starts the span and returns a closer that ends it when invoked:

func NewGetUser(...) (u *User, err error) {
    defer trace.In(ctx, "db.users.get")(&err)
    u, err = db.GetUser(ctx, id)
    return
}

Pass nil if the caller has no error to report.

func InjectHeader added in v0.8.0

func InjectHeader(ctx context.Context, h http.Header)

InjectHeader writes a W3C traceparent into h using the current span from ctx. No-op if ctx carries no span, or the span's IDs are the wrong length (defensive — our minting always produces the right shape).

The sampled flag is always set ("01") — nexus samples every request.

func Middleware

func Middleware(bus *Bus, service, endpoint, transport string) httpx.HandlerFunc

Middleware emits request.start and request.end events bracketing the handler chain, and stashes a *Span and the bus in gin.Context so child spans and Record() attach to the same trace.

If the inbound request carries a valid W3C traceparent header, the root span reuses its TraceID (and records ParentID from the upstream span) so the trace is stitched across services. Otherwise a fresh TraceID is minted.

func MountDashboard added in v0.38.0

func MountDashboard(g httpx.Group, bus *Bus)

MountDashboard mounts the trace introspection surface onto the supplied dashboard router group:

GET /events       → WebSocket live stream of trace events
GET /traces/:id   → reconstructed span tree for one trace

Called by the dashboard package — keeps the handlers in the package that owns the Bus.

func NewTraceID added in v0.3.0

func NewTraceID() string

NewTraceID mints the next trace ID in the same format the request middleware uses. Exposed for code paths that emit events outside the HTTP request lifecycle (e.g. the cron scheduler) so trace IDs stay uniform across the dashboard.

func ParseTraceparent added in v0.24.0

func ParseTraceparent(h string) (traceID, parentSpanID string, ok bool)

ParseTraceparent decodes a W3C traceparent header value and returns the trace + parent span IDs. Public wrapper around the package- private parser so cross-process integrations (pubsub consumers, queue workers, gRPC interceptors) can extract the upstream trace without each implementing W3C parsing.

traceID, parentSpanID, ok := trace.ParseTraceparent(headers["traceparent"])

Returns ok=false on any of: empty input, wrong number of segments, non-"00" version byte, wrong-length / non-hex IDs, all-zero IDs. Callers should fall back to minting a fresh trace when ok=false.

func Record

func Record(c *httpx.Ctx, name string, start time.Time, err error)

Record attaches a timed sub-operation (DB call, MQ publish, external HTTP) to the current request's trace as a leaf span. It emits a span.start / span.end pair using the caller-supplied start time so the waterfall places the bar at the right offset.

start := time.Now()
err := db.Query(...)
trace.Record(c, "db.users.get", start, err)

Prefer trace.In / trace.StartSpan for new code — they compose with ctx instead of needing *httpx.Ctx. Record remains for handlers already written against gin.

func StackOf added in v0.21.28

func StackOf(err error) string

StackOf walks an error chain via errors.As and returns the first captured stack trace, or "" when none is present. Lets observers (metrics middleware, trace publishers) extract the stack without needing to know whether the caller wrapped before returning.

func WithBus added in v0.24.0

func WithBus(ctx context.Context, bus *Bus) context.Context

WithBus stashes bus in ctx so SpanFromCtx / BusFromCtx readers downstream can find it. Used by code that builds a fresh ctx outside an HTTP request lifecycle (workers, cron jobs, message consumers) and wants its emitted spans to land on the dashboard's trace stream.

nil bus is treated as "leave ctx alone" — the caller doesn't have to guard with `if bus != nil { ctx = WithBus(ctx, bus) }` at every site.

func WithRemoteParent added in v0.24.0

func WithRemoteParent(ctx context.Context, traceID, parentSpanID, service, endpoint string) context.Context

WithRemoteParent installs a synthetic parent span in ctx so a subsequent StartSpan inherits the given trace + parent IDs. The returned ctx represents "we are continuing an upstream trace that began in another process / another goroutine".

The synthetic span is a placeholder — it does NOT emit a span.start event, and it should never have End() called on it (the ended flag is set so an accidental call is a no-op). Its only purpose is to be visible to SpanFromCtx so child StartSpan calls can read TraceID + SpanID off of it as their parent linkage.

Typical use from a pubsub consumer:

if tid, pid, ok := trace.ParseTraceparent(msg.Attrs["traceparent"]); ok {
    ctx = trace.WithRemoteParent(ctx, tid, pid, "subscriber", "topic:sub")
}
ctx, span := trace.StartSpan(ctx, "pubsub.consume:...", ...)

Empty traceID is treated as "no remote info" — ctx is returned unchanged so callers don't have to special-case missing headers.

Types

type Attr added in v0.8.0

type Attr struct {
	Key string
	Val any
}

Attr is a key/value annotation attached to a span. Surfaced in the dashboard's trace waterfall (attrs panel per span).

func Any added in v0.8.0

func Any(k string, v any) Attr

func Bool added in v0.8.0

func Bool(k string, v bool) Attr

func Int added in v0.8.0

func Int(k string, v int64) Attr

func Str added in v0.8.0

func Str(k, v string) Attr

Str / Int / Bool / Any are constructor sugar for the common attr types. They exist so call sites stay short:

trace.StartSpan(ctx, "db.users.get", trace.Str("id", userID))

type Bus

type Bus struct {
	// contains filtered or unexported fields
}

Bus is a bounded ring buffer + pub/sub. Slow subscribers drop events rather than block producers — the request path must never be held up by a stalled UI.

The ring and subscriber fan-out are SHARDED BY TRACE ID: with the dashboard open, every request publishes 2-3 events, and a single mutex here was the last process-wide serialization point on the hot path. Keying the shard on the trace means one trace's events always share a shard, so their relative order survives; cross-shard order is recovered where it matters (Subscribe backlogs) by the global monotonic ID every event already carries.

Full-size buses shard docBusShards ways; small ones (capacity below busShards²·2) stay single-shard, keeping exact global ring order for tests and tiny configs.

func BusFrom

func BusFrom(c *httpx.Ctx) (*Bus, bool)

func BusFromCtx

func BusFromCtx(ctx context.Context) (*Bus, bool)

BusFromCtx returns the Bus from context, if the trace middleware stashed one.

func NewBus

func NewBus(capacity int) *Bus

func (*Bus) Publish

func (b *Bus) Publish(e Event)

func (*Bus) Recent added in v1.78.0

func (b *Bus) Recent() []Event

Recent returns every event currently in the ring, oldest first (by the bus-wide ID). Unlike Subscribe it registers nothing — a one-off read for views that render the buffer as a page.

func (*Bus) SnapshotByTrace added in v0.8.0

func (b *Bus) SnapshotByTrace(traceID string) []Event

SnapshotByTrace returns every event currently in the ring whose TraceID matches, in publish order. Backs the dashboard's per-trace waterfall view. Returns nil when no events match. One trace lives in one shard, so this scans a single ring.

func (*Bus) Spans added in v1.78.0

func (b *Bus) Spans(id string) []*SpanNode

Spans reconstructs a trace's span tree from the ring buffer, ordered by start. Merges request.start / request.end (the root) and span.start / span.end (children) into one node per SpanID. Events without a SpanID (e.g. KindDownstream markers) are skipped — they'd have no bar to render. Nil when the trace is no longer (or never was) in the buffer.

func (*Bus) Subscribe

func (b *Bus) Subscribe(sinceID int64, buffer int) ([]Event, <-chan Event, func())

Subscribe atomically captures the backlog (events with ID > sinceID) and registers for future events. Per shard, backlog capture and registration happen under one lock, so within a shard a reconnecting client sees every event exactly once — no gap, no duplicate; each event lives in exactly one shard, so the guarantee is global. The merged backlog is sorted by the bus-wide monotonic ID.

Delivery is fanned in: each shard gets its own buffered channel and one forwarder goroutine moves events onto the subscriber's channel. Producers therefore only ever contend with their own shard — never with the other shards' publishes racing toward the same subscriber. A slow consumer backpressures the forwarders, the shard channels fill, and Publish drops — the same drop-don't-block contract as before. Per-trace ordering survives: one trace → one shard → one FIFO channel → one forwarder.

type Event

type Event struct {
	ID         int64  `json:"id"`
	TraceID    string `json:"traceId"`
	SpanID     string `json:"spanId,omitempty"`
	ParentID   string `json:"parentId,omitempty"`
	Name       string `json:"name,omitempty"`
	Kind       Kind   `json:"kind"`
	Service    string `json:"service,omitempty"`
	Endpoint   string `json:"endpoint,omitempty"`
	Transport  string `json:"transport,omitempty"`
	Method     string `json:"method,omitempty"`
	Path       string `json:"path,omitempty"`
	Status     int    `json:"status,omitempty"`
	DurationMs int64  `json:"durationMs,omitempty"`
	Message    string `json:"message,omitempty"`
	Error      string `json:"error,omitempty"`
	// Stack carries the captured Go runtime stack trace for events
	// that originated from a panic. The framework's recovery
	// middleware wraps the panic value in a *StackError; metrics +
	// trace publishers extract the stack via StackOf and attach it
	// here so the dashboard's error views can show "where did this
	// come from?" without operators tailing logs.
	Stack     string         `json:"stack,omitempty"`
	Remote    bool           `json:"remote,omitempty"`
	Timestamp time.Time      `json:"timestamp"`
	Meta      map[string]any `json:"meta,omitempty"`
}

type Kind

type Kind string
const (
	KindRequestStart Kind = "request.start"
	KindRequestEnd   Kind = "request.end"
	// KindRequestOp is emitted by the metrics middleware AFTER the
	// handler returns, carrying the specific op name in Endpoint so
	// UI consumers can drive per-endpoint visualisations (packet
	// animations, per-op trace rows). request.start from the trace
	// middleware uses the HTTP path — too coarse to identify a
	// GraphQL operation; request.op fills that gap.
	KindRequestOp Kind = "request.op"
	// KindDownstream is an untimed "X happened during this request"
	// marker (e.g. resource.using lookup). For timed sub-operations use
	// KindSpanStart / KindSpanEnd so they render as bars in the
	// waterfall.
	KindDownstream Kind = "downstream"
	KindLog        Kind = "log"
	// KindSpanStart / KindSpanEnd bracket a child span. Emitted by
	// StartSpan / (*Span).End and by trace.Record. The ParentID field
	// links children to their parent (the root request or an enclosing
	// span); the dashboard reconstructs the tree from it.
	KindSpanStart Kind = "span.start"
	KindSpanEnd   Kind = "span.end"
)

type Span

type Span struct {
	TraceID  string
	SpanID   string
	ParentID string
	Name     string
	Service  string
	Endpoint string
	Start    time.Time
	// Remote is true when this span's TraceID came from an inbound
	// W3C traceparent header (continuing an upstream trace) rather
	// than being minted fresh at ingress.
	Remote bool
	// contains filtered or unexported fields
}

Span represents one unit of work inside a trace. The root span is minted by the request Middleware (HTTP ingress); child spans are pushed with StartSpan and closed with End.

Span carries its bus pointer so End can publish without re-reading ctx — a handler may call End after the request's ctx has expired (deferred cleanup).

func NewRootSpan added in v0.25.0

func NewRootSpan(ctx context.Context, name, service, endpoint, transport string, attrs ...Attr) (context.Context, *Span, func(status int, err error))

NewRootSpan emits a request.start event on the bus carried by ctx and returns a ctx with a fresh root span installed, plus a finish func to call when the request is done. It's the transport- agnostic counterpart to the gin Middleware: WebSocket frames, pubsub consumers, background workers — anything that wants to be the root of a trace tree on the dashboard's waterfall — call this instead of building Event values by hand.

The returned span is also stored in ctx so child StartSpan calls inside the handler attach as children automatically.

finish(status, err) emits the matching request.end event. Recommend `defer finish(...)` from the dispatcher with the post- handler status + error in scope; calling finish more than once is safe (subsequent calls publish a new event each time, mirroring trace.Middleware's contract — the dashboard de-dupes by SpanID).

When ctx carries no bus (caller forgot WithBus), this is a no-op shim: the returned span has well-formed IDs, ctx-stash works for child spans, finish swallows. Code paths that touch the bus check for nil internally so the caller doesn't have to gate.

func SpanFrom

func SpanFrom(c *httpx.Ctx) (*Span, bool)

func SpanFromCtx

func SpanFromCtx(ctx context.Context) (*Span, bool)

SpanFromCtx reads the current span from any context.Context — root or child, whichever was pushed last. Use this from code paths that don't have a *httpx.Ctx (GraphQL resolvers via p.Context, GORM callbacks, worker code called from a request).

func StartRequest added in v1.44.0

func StartRequest(c *httpx.Ctx, bus *Bus, service, endpoint, transport string) (*Span, func())

StartRequest opens the root request span for c and publishes request.start. The returned finish func publishes the matching request.end (status, duration, accumulated errors). Middleware wraps the pair around c.Next(); a terminal handler that IS the end of the chain (nexus's AsRest handler) brackets its own body with it instead — calling c.Next() there would return immediately and stamp the end event before the handler ran.

func StartSpan added in v0.8.0

func StartSpan(ctx context.Context, name string, attrs ...Attr) (context.Context, *Span)

StartSpan pushes a child span under whatever span is currently in ctx and returns a derived ctx carrying the child. If ctx has no parent span or no bus, the returned span is a no-op stub — End is still safe to call.

Typical use:

ctx, span := trace.StartSpan(ctx, "rabbit.publish", trace.Str("topic", t))
err := ch.Publish(ctx, payload)
span.End(err)

func (*Span) End added in v0.8.0

func (s *Span) End(err error)

End closes the span and publishes a span.end event. Safe to call more than once — subsequent calls are no-ops. Pass nil for success; pass the handler's error for failure so it surfaces on the waterfall.

func (*Span) Set added in v0.8.0

func (s *Span) Set(key string, val any)

Set records one attribute on the span. Safe for concurrent use.

func (*Span) SetAttrs added in v0.8.0

func (s *Span) SetAttrs(attrs ...Attr)

SetAttrs applies a batch of attributes.

type SpanNode added in v1.78.0

type SpanNode struct {
	SpanID     string         `json:"spanId"`
	ParentID   string         `json:"parentId,omitempty"`
	Name       string         `json:"name"`
	Kind       string         `json:"kind"`
	Service    string         `json:"service,omitempty"`
	Endpoint   string         `json:"endpoint,omitempty"`
	Transport  string         `json:"transport,omitempty"`
	StartMs    int64          `json:"startMs"`
	DurationMs int64          `json:"durationMs"`
	Status     int            `json:"status,omitempty"`
	Error      string         `json:"error,omitempty"`
	Remote     bool           `json:"remote,omitempty"`
	Attrs      map[string]any `json:"attrs,omitempty"`
}

SpanNode is one node in the dashboard waterfall. Times are relative to the trace's earliest event so a UI can render bars without knowing the absolute clock.

type StackError added in v0.21.28

type StackError struct {
	Err   error
	Stack string
}

StackError is an error that carries a captured Go stack trace. Used by the framework's panic-recovery middleware to thread both the panic value AND the stack through gin's c.Error/c.Errors path, so downstream middleware (metrics, trace) can surface the stack on the dashboard via StackOf.

Direct use:

&trace.StackError{Err: fmt.Errorf("..."), Stack: string(debug.Stack())}

Errors that don't originate from a panic don't get a stack automatically; user code can opt in by wrapping at the source.

func (*StackError) Error added in v0.21.28

func (e *StackError) Error() string

func (*StackError) Unwrap added in v0.21.28

func (e *StackError) Unwrap() error

Unwrap lets errors.Is / errors.As / errors.Unwrap walk past the stack-carrier to the underlying error value.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL