graph

Documentation

Overview

Package graph provides an in-memory service dependency graph rebuilt periodically from recent span data. It is a processing accelerator — the relational DB remains the source of truth.

Index

• type DataProvider
• type EdgeKey
• type Graph
  • func New(provider DataProvider, windowSize, refreshEvery time.Duration) *Graph
  • func (g *Graph) Snapshot() *Snapshot
  • func (g *Graph) Start(ctx context.Context)
• type ServiceEdge
• type ServiceNode
• type Snapshot
• type SpanRow

Types

type DataProvider

type DataProvider func(since time.Time) ([]SpanRow, error)

DataProvider is the function the graph calls every refresh cycle to fetch recent spans. Decouples graph from storage layer.

type EdgeKey

type EdgeKey struct {
	Source string
	Target string
}

EdgeKey identifies a directed service-to-service call.

type Graph

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

Graph is a thread-safe in-memory service dependency graph.

func New

func New(provider DataProvider, windowSize, refreshEvery time.Duration) *Graph

New creates a Graph. refreshEvery controls how often it rebuilds from the DB. windowSize is the lookback window for span data (e.g. 5 minutes).

func (*Graph) Snapshot

func (g *Graph) Snapshot() *Snapshot

Snapshot returns the latest computed graph state (safe for concurrent reads).

func (*Graph) Start

func (g *Graph) Start(ctx context.Context)

Start rebuilds the graph on a background goroutine until ctx is cancelled.

type ServiceEdge

type ServiceEdge struct {
	Source       string
	Target       string
	CallCount    int64
	AvgLatencyMs float64
	ErrorRate    float64
	Status       string // "healthy" | "degraded" | "critical"
}

ServiceEdge is a directed dependency between two services.

type ServiceNode

type ServiceNode struct {
	Name        string
	HealthScore float64 // 0.0–1.0
	Status      string  // "healthy" | "degraded" | "critical"

	RequestRateRPS float64
	ErrorRate      float64
	AvgLatencyMs   float64
	P99LatencyMs   float64
	SpanCount      int64
	LogErrorCount  int64 // set externally by callers if needed

	Alerts []string
}

ServiceNode holds aggregated health data for a single service.

type Snapshot

type Snapshot struct {
	Nodes     map[string]*ServiceNode
	Edges     []ServiceEdge
	UpdatedAt time.Time
}

Snapshot is the immutable graph state returned to callers.

type SpanRow

type SpanRow struct {
	SpanID        string
	ParentSpanID  string
	ServiceName   string
	OperationName string
	DurationMs    float64
	IsError       bool
	Timestamp     time.Time
}

SpanRow is the minimal span data needed to build the graph. Callers supply this via the DataProvider to decouple the graph from GORM.