SPB Git

Repository Public

report.go 7.5 KB 204 lines go

1package protocol23import "time"45// Report is one telemetry batch (POST /agent/v1/report). Seq increases by one6// per report for the life of an agent identity; the server uses it to detect7// gaps and to discard duplicates replayed from the offline buffer.8type Report struct {9	V            int               `json:"v"`10	Seq          int64             `json:"seq"`11	TS           time.Time         `json:"ts"` // agent clock, UTC12	AgentVersion string            `json:"agent_version"`13	Buffered     bool              `json:"buffered,omitempty"` // replayed after a disconnection14	Samples      []Sample          `json:"samples"`15	Availability map[string]string `json:"availability,omitempty"` // metric name -> Avail*16	Processes    []Process         `json:"processes,omitempty"`17	Services     *ServiceSet       `json:"services,omitempty"`18	Inventory    *Inventory        `json:"inventory,omitempty"`19	Volumes      []Volume          `json:"volumes,omitempty"`20	Inference    *InferenceSet     `json:"inference,omitempty"`21	NAS          []NASProbe        `json:"nas,omitempty"`22	Capabilities []string          `json:"capabilities,omitempty"` // command types allowed by local policy23}2425type Sample struct {26	M string  `json:"m"`           // metric name from Catalog27	L string  `json:"l,omitempty"` // label28	V float64 `json:"v"`29}3031type Process struct {32	PID     int32   `json:"pid"`33	Name    string  `json:"name"`34	User    string  `json:"user"`35	CPU     float64 `json:"cpu"` // percent of one core36	RSS     int64   `json:"rss"`37	Threads int32   `json:"threads,omitempty"`38	Started int64   `json:"started,omitempty"` // unix seconds39	// The command line is deliberately NOT collected: arguments routinely contain secrets.40}4142// ServiceSet is a complete observation by one or more managers. A manager43// listed in Managers but with no entry in Items has zero services; a manager44// absent from Managers was not observed (its services are left untouched).45type ServiceSet struct {46	Managers []string  `json:"managers"`47	Items    []Service `json:"items"`48}4950type Service struct {51	Manager  string  `json:"manager"` // pm2 | launchd | systemd | docker52	Name     string  `json:"name"`53	State    string  `json:"state"`     // online | stopped | errored | unknown54	RawState string  `json:"raw_state"` // manager's own word55	PID      int32   `json:"pid,omitempty"`56	Restarts int32   `json:"restarts,omitempty"`57	MemBytes int64   `json:"mem_bytes,omitempty"`58	CPU      float64 `json:"cpu,omitempty"`59	UptimeS  int64   `json:"uptime_s,omitempty"`60	Version  string  `json:"version,omitempty"`61	Ports    []int   `json:"ports,omitempty"`62	Scope    string  `json:"scope,omitempty"` // launchd: user | system63}6465type Inventory struct {66	HardwareUUID string      `json:"hardware_uuid"`67	Hostname     string      `json:"hostname"`68	Kind         string      `json:"kind"` // mac | linux69	Model        string      `json:"model"`70	Chip         string      `json:"chip"`71	Arch         string      `json:"arch"`72	CPUCores     int         `json:"cpu_cores"`73	CPULevels    []CPULevel  `json:"cpu_levels,omitempty"` // as named by the OS; no P/E assumption74	GPUCores     int         `json:"gpu_cores,omitempty"`75	GPUModel     string      `json:"gpu_model,omitempty"`76	MemBytes     int64       `json:"mem_bytes"`77	StorageBytes int64       `json:"storage_bytes"`78	OSName       string      `json:"os_name"`79	OSVersion    string      `json:"os_version"`80	OSBuild      string      `json:"os_build"`81	Kernel       string      `json:"kernel"`82	BootTime     time.Time   `json:"boot_time"`83	Interfaces   []Interface `json:"interfaces"`84	Managers     []string    `json:"managers"` // service managers detected85	Laptop       bool        `json:"laptop"`86}8788type CPULevel struct {89	Name  string `json:"name"`90	Cores int    `json:"cores"`91}9293type Interface struct {94	Name    string   `json:"name"`95	Kind    string   `json:"kind"` // ethernet | wifi | tunnel | other96	MAC     string   `json:"mac,omitempty"`97	Addrs   []string `json:"addrs"`98	Media   string   `json:"media,omitempty"`99	Up      bool     `json:"up"`100	Default bool     `json:"default,omitempty"`101}102103type Volume struct {104	Mount  string `json:"mount"`105	Device string `json:"device"`106	FS     string `json:"fs"`107	Kind   string `json:"kind"` // internal | external | network108	Total  int64  `json:"total"`109	Used   int64  `json:"used"`110	SMART  string `json:"smart,omitempty"`  // verified | failing | "" when not observable111	Remote string `json:"remote,omitempty"` // network volumes: //host/share, credentials stripped112}113114type InferenceSet struct {115	Items []InferenceServer `json:"items"`116}117118type InferenceServer struct {119	Kind         string   `json:"kind"` // mlx_lm | ollama | llama.cpp120	Port         int      `json:"port"`121	Model        string   `json:"model,omitempty"`122	PID          int32    `json:"pid"`123	RSS          int64    `json:"rss"`124	UptimeS      int64    `json:"uptime_s"`125	DiskBytes    int64    `json:"disk_bytes,omitempty"`126	Health       string   `json:"health"` // ok | failing | unknown127	HealthMS     float64  `json:"health_ms,omitempty"`128	ListedModels []string `json:"listed_models,omitempty"`129}130131type NASProbe struct {132	Host      string  `json:"host"`133	Reachable bool    `json:"reachable"`134	LatencyMS float64 `json:"latency_ms,omitempty"`135	Mounted   bool    `json:"mounted"`136	Total     int64   `json:"total,omitempty"`137	Used      int64   `json:"used,omitempty"`138}139140// ReportAck is the server's answer to a report.141type ReportAck struct {142	Seq        int64     `json:"seq"`143	ServerTime time.Time `json:"server_time"`144	// Directives the agent applies to itself (all optional).145	IntervalS     int      `json:"interval_s,omitempty"`146	WantInventory bool     `json:"want_inventory,omitempty"`147	NASTargets    []string `json:"nas_targets,omitempty"` // hosts to probe on TCP 445148	RenewCert     bool     `json:"renew_cert,omitempty"`149}150151// Enrollment.152type EnrollRequest struct {153	CSRPEM       string    `json:"csr_pem"`154	Inventory    Inventory `json:"inventory"`155	AgentVersion string    `json:"agent_version"`156}157158type EnrollResponse struct {159	AgentID     string            `json:"agent_id"`160	NodeID      string            `json:"node_id"`161	CertPEM     string            `json:"cert_pem"`162	CAPEM       string            `json:"ca_pem"`163	CommandKeys map[string]string `json:"command_keys"` // key id -> base64 Ed25519 public key164	Endpoints   []string          `json:"endpoints"`165	ServerName  string            `json:"server_name"`166	IntervalS   int               `json:"interval_s"`167}168169type RenewRequest struct {170	CSRPEM string `json:"csr_pem"`171}172173type RenewResponse struct {174	CertPEM     string            `json:"cert_pem"`175	CAPEM       string            `json:"ca_pem"`176	CommandKeys map[string]string `json:"command_keys"`177}178179// Command lifecycle messages (agent -> ingest).180type CommandAck struct {181	Accepted bool   `json:"accepted"`182	Reason   string `json:"reason,omitempty"` // verification or policy refusal183}184185type CommandOutput struct {186	Stream string `json:"stream"` // stdout | stderr | info187	Data   string `json:"data"`   // already redacted by the agent188}189190type CommandResult struct {191	Status   string         `json:"status"` // succeeded | failed | timed_out | cancelled192	ExitCode *int           `json:"exit_code,omitempty"`193	Error    string         `json:"error,omitempty"`194	Result   map[string]any `json:"result,omitempty"`195	Duration float64        `json:"duration_s"`196}197198// CommandsResponse is the long-poll answer; Cancel lists command ids the199// agent should stop cooperatively.200type CommandsResponse struct {201	Commands []SignedCommand `json:"commands"`202	Cancel   []string        `json:"cancel,omitempty"`203}204
Files main
Menu

Theme