https://github.com/arl/runtimefs
Expose your Go application runtime metrics as a filesystem
https://github.com/arl/runtimefs
Last synced: 8 months ago
JSON representation
Expose your Go application runtime metrics as a filesystem
- Host: GitHub
- URL: https://github.com/arl/runtimefs
- Owner: arl
- License: mit
- Created: 2025-10-20T12:38:49.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-10-21T10:06:45.000Z (8 months ago)
- Last Synced: 2025-10-21T11:34:34.492Z (8 months ago)
- Language: Go
- Size: 8.79 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# runtimefs
Package runtimefs provides a FUSE filesystem that exposes runtime/metrics data as files and directories.
Metrics are organized in a directory hierarchy that mirrors their names.
- [runtimefs](#runtimefs)
- [Quick start](#quick-start)
- [Metric representation](#metric-representation)
- [Single value metrics (`KindFloat64`, `KindUint64`)](#single-value-metrics-kindfloat64-kinduint64)
- [Histogram metrics (kind `KindFloat64Histogram`)](#histogram-metrics-kind-kindfloat64histogram)
- [Example usages](#example-usages)
- [License](#license)
## Quick start
Install the library:
```
go get github.com/arl/runtimefs@latest
```
To quickly try it out and explore the created filesystem, just run:
```
cd /tmp
mkdir metrics
go run github.com/arl/runtimefs/cmd/example@latest metrics
```
**API**:
```go
// Mount mounts the runtime metrics filesystem at the given directory path. It
// returns a function to unmount the filesystem, or an error if the mount
// operation failed.
func Mount(dirpath string) (UnmountFunc, error)
// UnmountFunc is the type of the function to unmount the filesystem.
type UnmountFunc func() error
```
Example usage:
```go
package main
import (
"context"
"fmt"
"os"
"os/signal"
"github.com/arl/runtimefs"
)
const mountDir = "./mnt"
func main() {
unmount, _ := runtimefs.Mount(mountDir)
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
defer cancel()
<-ctx.Done()
err := unmount(); err != nil { /* handle error */ }
}
```
## Metric representation
### Single value metrics (`KindFloat64`, `KindUint64`)
Single value metrics are represented as a directory containing:
- a file named after the unit (e.g. `bytes`, `seconds`) that contains the current value
- a file named `description` that contains the metric description
- a file named `cumulative` (1 or 0) that indicates whether the metric is cumulative or not
For example, `/memory/classes/heap/objects` is shown as:
/memory/classes/heap/objects/
├── bytes
├── cumulative
└── description
### Histogram metrics (kind `KindFloat64Histogram`)
Histogram metrics are represented as a directory containing:
- a file named after the unit (e.g. `bytes`, `seconds`) that contains the current value (one line per bucket)
- a file named `buckets` that contains the bucket boundaries (one line per boundary)
- a file named `description` that contains the metric description
- a file named `cumulative` (1 or 0) that indicates whether the metric is cumulative or not
For example, `/sched/pauses/total/gc` is shown as:
/sched/pauses/total/gc/
├── buckets
├── bytes
├── cumulative
└── description
## Example usages
Print bytes on the heap:
```
cat /gc/heap/live/bytes
```
Monitor objects on the heap:
```
watch -n1 'expr $(cat /gc/heap/allocs/objects) - $(cat /gc/heap/frees/objects)'
```
Explore metrics:
```
tree
```
or
```
ls -R
```
Current distribution of GC pause durations:
```
paste /sched/pauses/total/gc/buckets /sched/pauses/total/gc/seconds
```
Find all histogram metrics:
```
find -name buckets
```
## License
MIT, see [LICENSE](LICENSE).