https://github.com/coder/clistat
https://github.com/coder/clistat
Last synced: 7 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/coder/clistat
- Owner: coder
- License: mit
- Created: 2025-03-03T16:39:10.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-05-27T17:12:33.000Z (8 months ago)
- Last Synced: 2025-06-11T05:51:53.008Z (7 months ago)
- Language: Go
- Size: 73.2 KB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# clistat
A Go library for measuring and reporting system resource usage.
## Overview
`clistat` provides utilities to query resource usage metrics on a system including:
- Host resources:
- CPU usage
- Memory usage
- Disk usage
- Container resources (cgroup v1 and v2 support):
- CPU usage
- Memory usage
## Features
- Human-readable output formatting with appropriate unit prefixes
- Support for both host and containerized environments
- Automatic container detection
- Support for both cgroup v1 and v2
- Configurable with options pattern
## Usage
The below sample code can be run as follows:
```shell
CGO_ENABLED=0 go run github.com/coder/clistat/cmd/clistat@main
```
```go
package main
import (
"fmt"
"log"
"github.com/coder/clistat"
)
func main() {
// Create a new Statter
s, err := clistat.New()
if err != nil {
log.Fatal(err)
}
// Query host CPU usage
cpu, err := s.HostCPU()
if err != nil {
log.Fatal(err)
}
fmt.Printf("CPU: %s\n", cpu)
// Query host memory usage
mem, err := s.HostMemory(clistat.PrefixGibi)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Memory: %s\n", mem)
// Query disk usage
disk, err := s.Disk(clistat.PrefixGibi, "")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Disk: %s\n", disk)
// Check if running in a container
isContainer, err := s.IsContainerized()
if err != nil {
log.Fatal(err)
}
if isContainer {
// Query container CPU usage
containerCPU, err := s.ContainerCPU()
if err != nil {
log.Fatal(err)
}
fmt.Printf("Container CPU: %s\n", containerCPU)
// Query container memory usage
containerMem, err := s.ContainerMemory(clistat.PrefixMebi)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Container Memory: %s\n", containerMem)
}
}
```
## Output Examples
The library formats output in a human-friendly way:
```
CPU: 2.5/8 cores (31%)
Memory: 3.2/16 GiB (20%)
Disk: 50/200 GiB (25%)
Container CPU: 0.5/2.5 cores (20%)
Container Memory: 256/1024 MiB (25%)
```
## Testing
The library includes a comprehensive test suite that can be run with:
```
go test ./...
```
Some tests are designed to detect containerization status and will adjust based on the environment. You can control test behavior with these environment variables:
- `CLISTAT_IS_CONTAINERIZED=yes` - Indicate tests are running in a container
- `CLISTAT_HAS_MEMORY_LIMIT=yes` - Indicate container has memory limits
- `CLISTAT_HAS_CPU_LIMIT=yes` - Indicate container has CPU limits