status

Documentation

Overview

Package status provides telemetry collection and HTTP server for node status reporting.

This package implements the node-side of the distributed telemetry system that enables real-time visibility into Citadel nodes on the AceTeam Fabric page.

Architecture:

• StatusCollector gathers metrics from system, GPU, and services
• StatusServer exposes an HTTP endpoint for on-demand queries
• Both are used by the heartbeat client for periodic reporting

Index

• Constants
• func GetSystemUptime() (int64, error)
• func InferServicePort(serviceName string) int
• func InferServiceType(serviceName string) string
• type Collector
  • func NewCollector(cfg CollectorConfig) *Collector
  • func (c *Collector) Collect() (*NodeStatus, error)
  • func (c *Collector) CollectCompact() (*NodeStatus, error)
• type CollectorConfig
• type GPUMetrics
• type HealthResponse
• type ModelDiscovery
  • func NewModelDiscovery() *ModelDiscovery
  • func (m *ModelDiscovery) CheckServiceHealth(ctx context.Context, serviceType string, port int) (string, error)
  • func (m *ModelDiscovery) DiscoverModels(ctx context.Context, serviceType string, port int) ([]string, error)
• type NodeInfo
• type NodeStatus
• type Server
  • func NewServer(cfg ServerConfig, collector *Collector) *Server
  • func (s *Server) Port() int
  • func (s *Server) Start(ctx context.Context) error
• type ServerConfig
• type ServiceConfig
• type ServiceInfo
• type SystemMetrics

Constants

const (
	ServiceTypeLLM      = "llm"
	ServiceTypeDatabase = "database"
	ServiceTypeOther    = "other"
)

ServiceType constants for service classification.

const (
	ServiceStatusRunning = "running"
	ServiceStatusStopped = "stopped"
	ServiceStatusError   = "error"
)

ServiceStatus constants for service state.

const (
	HealthStatusOK        = "ok"
	HealthStatusDegraded  = "degraded"
	HealthStatusUnhealthy = "unhealthy"
	HealthStatusUnknown   = "unknown"
)

HealthStatus constants for health checks.

const StatusVersion = "1.0"

StatusVersion is the current version of the status payload format.

Functions

func GetSystemUptime

func GetSystemUptime() (int64, error)

GetSystemUptime returns the host system uptime in seconds.

func InferServicePort

func InferServicePort(serviceName string) int

InferServicePort attempts to determine port from service name.

func InferServiceType

func InferServiceType(serviceName string) string

InferServiceType attempts to determine service type from name.

Types

type Collector

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

Collector gathers status metrics from the system, GPU, and services.

func NewCollector

func NewCollector(cfg CollectorConfig) *Collector

NewCollector creates a new status collector.

func (*Collector) Collect

func (c *Collector) Collect() (*NodeStatus, error)

Collect gathers all status metrics and returns a NodeStatus.

func (*Collector) CollectCompact

func (c *Collector) CollectCompact() (*NodeStatus, error)

CollectCompact returns a minimal status suitable for heartbeats.

type CollectorConfig

type CollectorConfig struct {
	NodeName  string
	ConfigDir string
	Services  []ServiceConfig
}

CollectorConfig holds configuration for the status collector.

type GPUMetrics

type GPUMetrics struct {
	Index              int     `json:"index"`
	Name               string  `json:"name"`
	MemoryUsedMB       int     `json:"memory_used_mb,omitempty"`
	MemoryTotalMB      int     `json:"memory_total_mb,omitempty"`
	UtilizationPercent float64 `json:"utilization_percent,omitempty"`
	TemperatureCelsius int     `json:"temperature_celsius,omitempty"`
	Driver             string  `json:"driver,omitempty"`
}

GPUMetrics contains GPU utilization information.

type HealthResponse

type HealthResponse struct {
	Status  string `json:"status"` // "ok", "degraded", "unhealthy"
	Version string `json:"version"`
}

HealthResponse is the response for /health endpoint.

type ModelDiscovery

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

ModelDiscovery provides model discovery for LLM services.

func NewModelDiscovery

func NewModelDiscovery() *ModelDiscovery

NewModelDiscovery creates a new model discovery instance.

func (*ModelDiscovery) CheckServiceHealth

func (m *ModelDiscovery) CheckServiceHealth(ctx context.Context, serviceType string, port int) (string, error)

CheckServiceHealth performs a health check on an LLM service.

func (*ModelDiscovery) DiscoverModels

func (m *ModelDiscovery) DiscoverModels(ctx context.Context, serviceType string, port int) ([]string, error)

DiscoverModels queries an LLM service for loaded models. It automatically detects the service type and uses the appropriate API.

type NodeInfo

type NodeInfo struct {
	Name          string `json:"name"`
	TailscaleIP   string `json:"tailscale_ip,omitempty"`
	UptimeSeconds int64  `json:"uptime_seconds"`
}

NodeInfo contains basic node identification.

type NodeStatus

type NodeStatus struct {
	Version   string        `json:"version"`
	Timestamp time.Time     `json:"timestamp"`
	Node      NodeInfo      `json:"node"`
	System    SystemMetrics `json:"system"`
	GPU       []GPUMetrics  `json:"gpu,omitempty"`
	Services  []ServiceInfo `json:"services,omitempty"`
}

NodeStatus represents the complete status of a Citadel node. This is the payload sent in heartbeats and returned from /status endpoint.

type Server

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

Server provides an HTTP server for node status queries. This enables on-demand queries from the AceTeam control plane.

func NewServer

func NewServer(cfg ServerConfig, collector *Collector) *Server

NewServer creates a new status HTTP server.

func (*Server) Port

func (s *Server) Port() int

Port returns the port the server is configured to listen on.

func (*Server) Start

func (s *Server) Start(ctx context.Context) error

Start begins listening for HTTP requests. This method blocks until the context is cancelled.

type ServerConfig

type ServerConfig struct {
	Port    int    // HTTP server port (default: 8080)
	Version string // Citadel version string
}

ServerConfig holds configuration for the status server.

type ServiceConfig

type ServiceConfig struct {
	Name        string
	Type        string // "llm", "database", "other"
	ComposeFile string
	Port        int
}

ServiceConfig holds the configuration for a service from the manifest.

type ServiceInfo

type ServiceInfo struct {
	Name   string   `json:"name"`
	Type   string   `json:"type"`   // "llm", "database", "other"
	Status string   `json:"status"` // "running", "stopped", "error"
	Port   int      `json:"port,omitempty"`
	Health string   `json:"health,omitempty"` // "healthy", "unhealthy", "unknown"
	Models []string `json:"models,omitempty"` // For LLM services
}

ServiceInfo contains information about a running service.

type SystemMetrics

type SystemMetrics struct {
	CPUPercent    float64 `json:"cpu_percent"`
	MemoryUsedGB  float64 `json:"memory_used_gb"`
	MemoryTotalGB float64 `json:"memory_total_gb"`
	MemoryPercent float64 `json:"memory_percent"`
	DiskUsedGB    float64 `json:"disk_used_gb"`
	DiskTotalGB   float64 `json:"disk_total_gb"`
	DiskPercent   float64 `json:"disk_percent"`
}

SystemMetrics contains system resource utilization.