🧙 Acolyte

Would you like to know the secret to eternal happiness?

Acolyte is a lightweight resource monitoring tool designed to collect statistics in containerized environments, particularly Kubernetes.

Acolyte monitors CPU, memory, and GPU utilization and writes the data as JSON to rotated files or standard output for easy consumption by other services. It's designed to run alongside your application in the same container and built with compatibility in mind.

Acolyte is configured through environment variables – by default, you don't necessarily have to configure anything.

General

• RUST_LOG: log level e.g. debug; default: info
• ACOLYTE_NO_RESTART: if set, Acolyte will not restart itself if it encounters an error; default: false

Collection

• ACOLYTE_STAT_INTERVAL_MS: interval between stats collection in milliseconds; default: 5000
• ACOLYTE_CPU_SAMPLE_RATE_MS: sample window for CPU usage in milliseconds; default: 100

Output

• ACOLYTE_OUTPUT_MODE: dir (default): write to files in ACOLYTE_STATS_DIR, stdout: write to standard output

Stats directory

• ACOLYTE_STATS_DIR: directory where stat files are written; default: /tmp/acolyte/stats
• ACOLYTE_MAX_STATS_ENTRIES: maximum number of stat files to keep; default: 12

Sentry

• SENTRY_DSN: optional Sentry DSN for error reporting
• CLUSTER_NAME: optional cluster identification for Sentry

# you probably want to run it in the background in your container
./acolyte &

# or attach it to an already running Kubernetes Pod
kubectl cp ./target/x86_64-unknown-linux-musl/release/acolyte my-pod:/tmp/acolyte
kubectl exec my-pod -- sh -c "/tmp/acolyte &"

The JSON fields are fairly self-explanatory e.g. stats-1741860918020.json:

{
  "time": 1741860918.0206466,
  "num_cpus": 20.0,
  "cpu_usage": 3.5053825547467063,
  "memory_usage_kb": 22802796,
  "memory_total_kb": 65542712,
  "num_gpus": 1,
  "gpu_usage": 0.23,
  "gpu_memory_usage_kb": 50176,
  "gpu_memory_total_kb": 8388608
}

Development

cargo test

RUST_LOG=debug cargo run

Build

For release, you should build it as a musl static binary:

rustup target add x86_64-unknown-linux-musl

# https://rust-lang.github.io/rfcs/1721-crt-static.html#specifying-dynamicstatic-c-runtime-linkage
# the flag is enabled by default for this specific target but 🤷
RUSTFLAGS="-C target-feature=+crt-static" cargo build --release --target x86_64-unknown-linux-musl

RUST_LOG=debug target/x86_64-unknown-linux-musl/release/acolyte

Release

GitHub will build and host new binaries on every version tag push on the main branch.

git checkout main
git pull origin main

# edit Cargo.toml to update version
git add Cargo.toml
git commit -m 'Become vx.y.z'

git tag vx.y.z
git push origin main vx.y.z