observability

Documentation

Overview

Package observability holds the cross-cutting request-log, stats, and distributed-tracing primitives used by the AWS gateway, the reverse proxy, the admin API, and the dataplane. The types defined here form the wire schema for everything CloudMock exposes via /api/requests/* and /api/traces/*; the gateway package keeps backwards-compatible aliases so existing importers (~50 service tests, the admin API, dataplane stores) continue to work without changes.

Index

• func GenerateSpanID() string
• func GenerateTraceID() string
• func NextRequestID() int64
• type RequestBroadcaster
• type RequestEntry
• type RequestFilter
• type RequestLog
  • func NewRequestLog(capacity int) *RequestLog
  • func (rl *RequestLog) Add(entry RequestEntry)
  • func (rl *RequestLog) GetByID(id string) *RequestEntry
  • func (rl *RequestLog) Recent(service string, limit int) []RequestEntry
  • func (rl *RequestLog) RecentFiltered(f RequestFilter) []RequestEntry
• type RequestStats
  • func NewRequestStats() *RequestStats
  • func (rs *RequestStats) Increment(svcName string)
  • func (rs *RequestStats) Snapshot() map[string]int64
• type TimelineSpan
• type TraceContext
• type TraceStore
  • func NewTraceStore(capacity int) *TraceStore
  • func (ts *TraceStore) Add(trace *TraceContext)
  • func (ts *TraceStore) CountInRange(start, end time.Time) int64
  • func (ts *TraceStore) Get(traceID string) *TraceContext
  • func (ts *TraceStore) Recent(service string, hasError *bool, limit int) []TraceSummary
  • func (ts *TraceStore) Timeline(traceID string) []TimelineSpan
• type TraceSummary

Functions

func GenerateSpanID

func GenerateSpanID() string

GenerateSpanID returns a new unique W3C-compatible span ID (16 hex chars).

func GenerateTraceID

func GenerateTraceID() string

GenerateTraceID returns a new unique W3C-compatible trace ID (32 hex chars).

func NextRequestID

func NextRequestID() int64

NextRequestID returns a fresh monotonic int from the shared request-ID counter. Used by middleware that constructs RequestEntry IDs.

Types

type RequestBroadcaster

type RequestBroadcaster interface {
	Broadcast(eventType string, data any)
}

RequestBroadcaster is an optional interface for broadcasting request events.

type RequestEntry

type RequestEntry struct {
	ID             string            `json:"id"`
	TraceID        string            `json:"trace_id,omitempty"`
	SpanID         string            `json:"span_id,omitempty"`
	Timestamp      time.Time         `json:"timestamp"`
	Service        string            `json:"service"`
	Action         string            `json:"action"`
	Method         string            `json:"method"`
	Path           string            `json:"path"`
	StatusCode     int               `json:"status_code"`
	Latency        time.Duration     `json:"latency_ns"`
	LatencyMs      float64           `json:"latency_ms"`
	CallerID       string            `json:"caller_id"`
	Error          string            `json:"error,omitempty"`
	Level          string            `json:"level,omitempty"`        // "app" (user-facing) or "infra" (AWS SDK calls to cloudmock)
	MemAllocKB     int64             `json:"mem_alloc_kb,omitempty"` // heap allocation at request time
	Goroutines     int               `json:"goroutines,omitempty"`   // goroutine count at request time
	RequestHeaders map[string]string `json:"request_headers,omitempty"`
	RequestBody    string            `json:"request_body,omitempty"`
	ResponseBody   string            `json:"response_body,omitempty"`
}

RequestEntry holds data about a single request processed by the gateway.

type RequestFilter

type RequestFilter struct {
	Service      string
	Path         string
	Method       string
	CallerID     string
	Action       string
	ErrorOnly    bool
	TraceID      string
	Level        string // "app" or "infra" — empty means all
	Limit        int
	TenantID     string
	OrgID        string
	UserID       string
	MinLatencyMs float64
	MaxLatencyMs float64
	From         time.Time
	To           time.Time
}

RequestFilter defines filtering criteria for request log queries.

type RequestLog

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

RequestLog is a thread-safe circular buffer of recent request entries.

func NewRequestLog

func NewRequestLog(capacity int) *RequestLog

NewRequestLog creates a RequestLog with the given capacity.

func (*RequestLog) Add

func (rl *RequestLog) Add(entry RequestEntry)

Add appends an entry to the circular buffer.

func (*RequestLog) GetByID

func (rl *RequestLog) GetByID(id string) *RequestEntry

GetByID returns the entry with the given ID, or nil if not found.

func (*RequestLog) Recent

func (rl *RequestLog) Recent(service string, limit int) []RequestEntry

Recent returns up to limit entries, newest first. If service is non-empty, only entries matching that service are returned.

func (*RequestLog) RecentFiltered

func (rl *RequestLog) RecentFiltered(f RequestFilter) []RequestEntry

RecentFiltered returns entries matching all non-empty filter fields.

type RequestStats

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

RequestStats tracks per-service request counts using atomic counters.

func NewRequestStats

func NewRequestStats() *RequestStats

NewRequestStats creates an empty RequestStats tracker.

func (*RequestStats) Increment

func (rs *RequestStats) Increment(svcName string)

Increment increments the counter for the given service.

func (*RequestStats) Snapshot

func (rs *RequestStats) Snapshot() map[string]int64

Snapshot returns a map of service name to request count.

type TimelineSpan

type TimelineSpan struct {
	SpanID        string            `json:"span_id"`
	ParentSpanID  string            `json:"parent_span_id,omitempty"`
	Service       string            `json:"service"`
	Action        string            `json:"action"`
	StartOffsetMs float64           `json:"start_offset_ms"`
	DurationMs    float64           `json:"duration_ms"`
	StatusCode    int               `json:"status_code"`
	Error         string            `json:"error,omitempty"`
	Depth         int               `json:"depth"`
	Metadata      map[string]string `json:"metadata,omitempty"`
}

TimelineSpan is a flattened span for waterfall rendering.

type TraceContext

type TraceContext struct {
	TraceID      string          `json:"trace_id"`
	SpanID       string          `json:"span_id"`
	ParentSpanID string          `json:"parent_span_id,omitempty"`
	Service      string          `json:"service"`
	Action       string          `json:"action"`
	Method       string          `json:"method,omitempty"`
	Path         string          `json:"path,omitempty"`
	StartTime    time.Time       `json:"start_time"`
	EndTime      time.Time       `json:"end_time"`
	Duration     time.Duration   `json:"duration_ns"`
	DurationMs   float64         `json:"duration_ms"`
	StatusCode   int             `json:"status_code"`
	Error        string          `json:"error,omitempty"`
	Children     []*TraceContext `json:"children,omitempty"`
	// Context propagation: feature flags, cache, policy decisions
	Metadata map[string]string `json:"metadata,omitempty"`
}

TraceContext represents a single span in a distributed trace.

type TraceStore

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

TraceStore is a thread-safe circular buffer of recent traces, indexed by TraceID.

func NewTraceStore

func NewTraceStore(capacity int) *TraceStore

NewTraceStore creates a TraceStore with the given capacity.

func (*TraceStore) Add

func (ts *TraceStore) Add(trace *TraceContext)

Add stores a trace span. If a trace with the same TraceID already exists and the span has a ParentSpanID, it is attached as a child of the parent span in the existing trace tree. Otherwise, a new root trace is created.

func (*TraceStore) CountInRange

func (ts *TraceStore) CountInRange(start, end time.Time) int64

CountInRange returns the number of traces with StartTime in [start, end).

func (*TraceStore) Get

func (ts *TraceStore) Get(traceID string) *TraceContext

Get returns the trace with the given ID, or nil if not found.

func (*TraceStore) Recent

func (ts *TraceStore) Recent(service string, hasError *bool, limit int) []TraceSummary

Recent returns up to limit traces, newest first. Supports filtering by service and status.

func (*TraceStore) Timeline

func (ts *TraceStore) Timeline(traceID string) []TimelineSpan

Timeline returns a flattened waterfall view of the trace.

type TraceSummary

type TraceSummary struct {
	TraceID     string  `json:"trace_id"`
	RootService string  `json:"root_service"`
	RootAction  string  `json:"root_action"`
	Method      string  `json:"method"`
	Path        string  `json:"path"`
	DurationMs  float64 `json:"duration_ms"`
	StatusCode  int     `json:"status_code"`
	SpanCount   int     `json:"span_count"`
	HasError    bool    `json:"has_error"`
	StartTime   string  `json:"start_time"`
}

TraceSummary is a lightweight representation for listing traces.