// Package seheweit collects instance observations without controlling the // observed workload. Authorization, queue execution and persistence belong to // its callers. It does not inspect document contents or contact remote services. package seheweit import ( "errors" "io" "math" "os" "path/filepath" "runtime" "strconv" "strings" "syscall" "time" "github.com/google/uuid" ) // Identity survives multiple collectors, but not a process restart/PID reuse. var processID = uuid.NewString() type ProcessIO struct { Scope string `json:"scope"` Available bool `json:"available"` ProcessID string `json:"process_id"` ReadBytes uint64 `json:"read_bytes"` WriteBytes uint64 `json:"write_bytes"` } type CPU struct { LogicalCPUs int `json:"logical_cpus"` LoadAverage string `json:"load_average"` } type Memory struct { HeapBytes uint64 `json:"heap_bytes"` GoSystemBytes uint64 `json:"go_system_bytes"` GCCycles uint32 `json:"gc_cycles"` Goroutines int `json:"goroutines"` } type Storage struct { Path string `json:"path"` TotalBytes uint64 `json:"total_bytes"` UsedBytes uint64 `json:"used_bytes"` AvailableBytes uint64 `json:"available_bytes"` } // Queue contains observations supplied by the application, not execution hooks. type Queue struct { Stats QueueStats `json:"stats"` ActiveWorkers int64 `json:"active_workers"` Paused bool `json:"paused"` } type QueueStats struct { Queued int `json:"queued"` Running int `json:"running"` } // Snapshot preserves the resource API and history JSON field names. // Sources are sampled sequentially, not in an atomic cross-source transaction. type Snapshot struct { TimestampMS int64 `json:"timestamp_ms"` IO ProcessIO `json:"io"` CPU CPU `json:"cpu"` Memory Memory `json:"memory"` Storage Storage `json:"storage"` Queue Queue `json:"queue"` } type sources struct { now func() time.Time readFile func(string) ([]byte, error) statfs func(string, *syscall.Statfs_t) error memory func(*runtime.MemStats) cpus func() int goroutines func() int } // Collect reads Go runtime counters, two bounded proc files and Statfs on the // configured document root. No directory walk, shell or background loop. func Collect(root string, queue Queue) Snapshot { return collect(root, queue, sources{ now: time.Now, readFile: readProcFile, statfs: syscall.Statfs, memory: runtime.ReadMemStats, cpus: runtime.NumCPU, goroutines: runtime.NumGoroutine, }) } func collect(root string, queue Queue, src sources) Snapshot { var mem runtime.MemStats src.memory(&mem) if root == "" { root = "." } if absolute, err := filepath.Abs(root); err == nil { root = absolute } storage := Storage{Path: root} var fs syscall.Statfs_t if err := src.statfs(root, &fs); err == nil { storage = storageCounters(root, fs.Blocks, fs.Bavail, fs.Bsize) } loadAverage := "" if data, err := src.readFile("/proc/loadavg"); err == nil { fields := strings.Fields(string(data)) if len(fields) >= 3 { loadAverage = strings.Join(fields[:3], " ") } } var ioData []byte if data, err := src.readFile("/proc/self/io"); err == nil { ioData = data } return Snapshot{ TimestampMS: src.now().UnixMilli(), IO: ParseProcessIO(string(ioData)), CPU: CPU{LogicalCPUs: src.cpus(), LoadAverage: loadAverage}, Memory: Memory{HeapBytes: mem.HeapAlloc, GoSystemBytes: mem.Sys, GCCycles: mem.NumGC, Goroutines: src.goroutines()}, Storage: storage, Queue: queue, } } func storageCounters(path string, blocks, available uint64, blockSize int64) Storage { result := Storage{Path: path} // Preserve the existing zero fallback rather than wrapping unsigned values. if blockSize <= 0 || available > blocks || blocks > math.MaxUint64/uint64(blockSize) { return result } result.TotalBytes = blocks * uint64(blockSize) result.AvailableBytes = available * uint64(blockSize) result.UsedBytes = result.TotalBytes - result.AvailableBytes return result } const maxProcBytes = 16 << 10 func readProcFile(path string) ([]byte, error) { f, err := os.Open(path) if err != nil { return nil, err } defer f.Close() data, err := io.ReadAll(io.LimitReader(f, maxProcBytes+1)) if err != nil { return nil, err } if len(data) > maxProcBytes { return nil, errors.New("resource counter file too large") } return data, nil } // ParseProcessIO uses actual storage bytes, not rchar/wchar (syscall traffic). // Partial, missing or invalid counters are unavailable, not a zero I/O rate. func ParseProcessIO(data string) ProcessIO { result := ProcessIO{Scope: "process", ProcessID: processID} read, write := false, false for _, line := range strings.Split(data, "\n") { fields := strings.Fields(line) if len(fields) != 2 || (fields[0] != "read_bytes:" && fields[0] != "write_bytes:") { continue } value, err := strconv.ParseUint(fields[1], 10, 64) if err != nil { return result } if fields[0] == "read_bytes:" { result.ReadBytes, read = value, true } else { result.WriteBytes, write = value, true } } result.Available = read && write return result }