fleet

Documentation

Overview

Package fleet provides an HTTP fan-out client for querying multiple Ingero nodes and concatenating results. Used by `ingero query --nodes` and `ingero explain --nodes` to provide cross-node investigation from a single CLI.

Architecture: client-side fan-out only. Each node runs its own dashboard API. The fleet client sends concurrent HTTP requests and concatenates the results. No central aggregation service — the user's CLI is the merge point.

Index

• Constants
• func FormatClockSkewWarnings(results []ClockSkewResult, thresholdMs float64) []string
• func PrintClockSkewWarnings(results []ClockSkewResult, thresholdMs float64) string
• type ChainEntry
• type ChainResult
• type Client
  • func New(cfg Config) (*Client, error)
  • func (c *Client) EstimateClockSkew(ctx context.Context) ([]ClockSkewResult, error)
  • func (c *Client) QueryChains(ctx context.Context, since string) (*ChainResult, error)
  • func (c *Client) QueryEndpoint(ctx context.Context, path string) (*GenericResult, error)
  • func (c *Client) QuerySQL(ctx context.Context, sql string) (*QueryResult, error)
• type ClockSkewResult
  • func (r ClockSkewResult) String() string
• type Config
• type GenericResult
• type QueryResult

Constants

const DefaultLimit = 1000

DefaultLimit is the max rows returned per node.

const DefaultTimeout = 5 * time.Second

DefaultTimeout is the per-node HTTP request timeout.

Functions

func FormatClockSkewWarnings

func FormatClockSkewWarnings(results []ClockSkewResult, thresholdMs float64) []string

FormatClockSkewWarnings returns warning strings for offsets exceeding the threshold.

func PrintClockSkewWarnings

func PrintClockSkewWarnings(results []ClockSkewResult, thresholdMs float64) string

PrintClockSkewWarnings prints warnings to stderr-style output string.

Types

type ChainEntry

type ChainEntry struct {
	Node            string   `json:"node"`
	ID              string   `json:"id"`
	DetectedAt      string   `json:"detected_at"`
	Severity        string   `json:"severity"`
	Summary         string   `json:"summary"`
	RootCause       string   `json:"root_cause"`
	Explanation     string   `json:"explanation"`
	Recommendations []string `json:"recommendations,omitempty"`
	CUDAOp          string   `json:"cuda_op,omitempty"`
	CUDAP99US       int64    `json:"cuda_p99_us,omitempty"`
	CUDAP50US       int64    `json:"cuda_p50_us,omitempty"`
	TailRatio       float64  `json:"tail_ratio,omitempty"`
}

ChainEntry is a causal chain from a remote node.

type ChainResult

type ChainResult struct {
	Chains   []ChainEntry // merged chains sorted by severity
	Warnings []string     // errors from individual nodes
}

ChainResult holds the merged result of a fan-out chain query.

type Client

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

Client is an HTTP fan-out client for fleet queries.

func New

func New(cfg Config) (*Client, error)

New creates a fleet client from the given config.

func (*Client) EstimateClockSkew

func (c *Client) EstimateClockSkew(ctx context.Context) ([]ClockSkewResult, error)

EstimateClockSkew estimates pairwise clock offsets across all configured nodes. Uses NTP-style one-shot estimation with 3 samples per node (median). The querying machine's clock is used as the reference.

func (*Client) QueryChains

func (c *Client) QueryChains(ctx context.Context, since string) (*ChainResult, error)

QueryChains fans out a chain query to all nodes and merges results sorted by severity.

func (*Client) QueryEndpoint

func (c *Client) QueryEndpoint(ctx context.Context, path string) (*GenericResult, error)

QueryEndpoint fans out a GET request to a path on each node and returns raw JSON per node. Used for /api/v1/ops, /api/v1/overview, etc. where response schemas vary by endpoint.

func (*Client) QuerySQL

func (c *Client) QuerySQL(ctx context.Context, sql string) (*QueryResult, error)

QuerySQL fans out a SQL query to all configured nodes and concatenates results. The result has a "node" column prepended to identify each row's origin.

type ClockSkewResult

type ClockSkewResult struct {
	NodeA    string
	NodeB    string
	OffsetMs float64 // positive = NodeB ahead of NodeA
	RTTMs    float64 // round-trip time of the measurement
}

ClockSkewResult represents the estimated clock offset between two nodes.

func (ClockSkewResult) String

func (r ClockSkewResult) String() string

String returns a human-readable clock skew description.

type Config

type Config struct {
	Nodes      []string      // host:port addresses
	Timeout    time.Duration // per-node timeout (0 = DefaultTimeout)
	Limit      int           // per-node row limit (0 = DefaultLimit)
	CACert     string        // path to CA cert for mTLS (empty = plain HTTP)
	ClientCert string        // path to client cert for mTLS
	ClientKey  string        // path to client key for mTLS
}

Config configures the fleet client.

type GenericResult

type GenericResult struct {
	Nodes    map[string]json.RawMessage // node addr → raw JSON response
	Warnings []string
}

GenericResult holds the result of a fan-out GET request returning raw JSON per node.

type QueryResult

type QueryResult struct {
	Columns  []string // column names (first is "node")
	Rows     [][]any  // row data
	Warnings []string // errors from individual nodes
}

QueryResult holds the merged result of a fan-out SQL query.