trace

package

v0.4.2 Latest Latest Go to latest Published: Apr 23, 2026 License: MIT Imports: 6 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/paulmanoni/nexus

Links

Open Source Insights

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 ¶

func Middleware(bus *Bus, service, endpoint, transport string) gin.HandlerFunc
func NewTraceID() string
func Record(c *gin.Context, name string, start time.Time, err error)
type Bus
- func (b *Bus) Publish(e Event)
- func (b *Bus) Subscribe(sinceID int64, buffer int) ([]Event, <-chan Event, func())
type Event
type Kind
type Span
- func SpanFrom(c *gin.Context) (*Span, bool)
- func SpanFromCtx(ctx context.Context) (*Span, bool)

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Middleware ¶

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

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

func NewTraceID ¶ added in v0.3.0

func NewTraceID() string

NewTraceID mints the next short, monotonic 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 Record ¶

func Record(c *gin.Context, name string, start time.Time, err error)

Record attaches a downstream event (DB call, MQ publish, external HTTP, etc.) to the current request's trace. Typical use:

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

Types ¶

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.

func BusFrom ¶

func BusFrom(c *gin.Context) (*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 (b *Bus) Subscribe(sinceID int64, buffer int) ([]Event, <-chan Event, func())

Subscribe atomically captures the backlog (events with ID > sinceID) and registers a channel for future events. Doing both under one lock guarantees a reconnecting client sees every event exactly once — no gap, no duplicate.

type Event ¶

type Event struct {
	ID         int64          `json:"id"`
	TraceID    string         `json:"traceId"`
	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"`
	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 Kind = "downstream"
	KindLog        Kind = "log"
)

type Span ¶

type Span struct {
	TraceID  string
	Service  string
	Endpoint string
	Start    time.Time
}

func SpanFrom ¶

func SpanFrom(c *gin.Context) (*Span, bool)

func SpanFromCtx ¶

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

SpanFromCtx reads the current request's Span from any context.Context. Use this from code paths that don't have a *gin.Context — GraphQL resolvers (via p.Context), GORM callbacks, downstream HTTP clients.

Source Files ¶

View all Source files

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