Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerLib/llms.txt

Use this file to discover all available pages before exploring further.

Snapshot captures a point-in-time (or time-averaged) view of a server’s resource metrics into a plain Python object. Pass a GenericServer or MinecraftServer to the constructor and read off ram, cpu, network_in, network_out, uptime, and — for Minecraft servers — tps and players. When duration > 0, the constructor blocks while collecting multiple samples and returns their mean, optionally trimming outliers first. 
from hungerlib.utils.utils import Snapshot

# Instant snapshot
snap = Snapshot(mc_server)
print(snap)

# Smoothed snapshot: sample for 5 s at 0.5 s intervals, drop 1 outlier per metric
snap = Snapshot(mc_server, duration=5.0, interval=0.5, drop_outliers=1)
print(f"Smoothed RAM: {snap.ram} MB  TPS: {snap.tps}")

​
Constructor

Snapshot(
    Server,
    rounding: int = 2,
    duration: float = 0.0,
    interval: float = 0.5,
    drop_outliers: int = 0,
    gb: bool = False,
)
​
Server
GenericServer | MinecraftServer
required
The server object to sample. Any object that implements getRAM(), getCPU(), getNetworkIn(), getNetworkOut(), and getUptime() is accepted. If the object also exposes getTPS() and getPlayers() (i.e. a MinecraftServer), those metrics are captured too.
​
rounding
int
default:"2"
Number of decimal places passed to getRAM(), getNetworkIn(), and getNetworkOut(). Does not affect cpu, tps, or players.
​
duration
float
default:"0.0"
Total sampling window in seconds. When 0.0 (default), a single instantaneous reading is taken and the constructor returns immediately. When > 0, the constructor blocks and collects samples at interval-second intervals until duration seconds have elapsed, then averages the results.
​
interval
float
default:"0.5"
Delay in seconds between samples when duration > 0. A value of 0.5 collects two samples per second. Has no effect when duration == 0.
​
drop_outliers
int
default:"0"
Number of extreme samples (lowest and highest) to remove per metric before computing the mean. For example, drop_outliers=1 sorts the sample list, drops the single lowest and single highest value, then averages the remainder. Has no effect when duration == 0 or when there are not enough samples remaining after trimming.
​
gb
bool
default:"False"
When True, RAM and network metrics are collected in gigabytes. When False (default), they are collected in megabytes.

​
Instance Attributes

After construction, the following attributes are available on the snapshot object. All floating-point values reflect the rounding and gb settings passed to the constructor.
​
ram
float | None
RAM usage in MB (or GB when gb=True). None if the server did not report a value. For smoothed snapshots, this is the mean of all collected samples after outlier trimming.
​
cpu
float | None
CPU usage as an absolute percentage (e.g. 45.67). None if unavailable. Mean for smoothed snapshots.
​
network_in
float | None
Cumulative inbound network usage in MB or GB. None if unavailable. Mean for smoothed snapshots.
​
network_out
float | None
Cumulative outbound network usage in MB or GB. None if unavailable. Mean for smoothed snapshots.
​
tps
float | None
Current TPS (ticks per second) from HungerBridge. Always set on the snapshot object. None for GenericServer instances (which lack getTPS()), or if the bridge is unreachable. Mean for smoothed snapshots.
​
players
int | float | None
Number of online players from HungerBridge. Always set on the snapshot object. None for GenericServer instances (which lack getPlayers()). For smoothed snapshots, this is the mean of sampled counts (may be a float).
​
uptime
int | None
Server uptime in seconds at the time of snapshot construction. Captured once — not smoothed even when duration > 0.
​
uptime_formatted
str | None
Human-readable uptime string, e.g. "2h 15m", "45m 30s", or "12s". Captured once alongside uptime.

​
Smoothing Behaviour

When duration > 0, the constructor enters a sampling loop:
  1. On each iteration it calls getRAM(), getCPU(), getNetworkIn(), getNetworkOut(), and (if available) getTPS() and getPlayers().
  2. It sleeps for interval seconds, then repeats until time.time() exceeds the start time plus duration.
  3. After sampling, each metric’s list is sorted. If drop_outliers > 0, the N lowest and N highest values are removed.
  4. The remaining values are averaged with statistics.mean().
This is especially useful for smoothing CPU and TPS spikes caused by garbage collection or chunk loading: 
# Sample for 10 seconds, 4 samples/sec, trim 2 outliers per metric
snap = Snapshot(mc_server, duration=10.0, interval=0.25, drop_outliers=2)
uptime and uptime_formatted are always captured exactly once at the end of the sampling window, not averaged.

​
__str__

Snapshot.__str__() returns a multi-line human-readable summary: 
Server: survival
Uptime: 2h 15m
RAM: 3521.48
CPU: 42.17
Network (in): 128.34
Network (out): 64.12
TPS: 19.982
Online players: 7
The TPS and Online players lines are only included when those attributes are not None. 
snap = Snapshot(mc_server, duration=3.0)
print(snap)

​
GenericServer vs MinecraftServer

AttributeGenericServerMinecraftServer
ram✅✅
cpu✅✅
network_in✅✅
network_out✅✅
uptime✅✅
uptime_formatted✅✅
tpsNone✅ (requires HungerBridge)
playersNone✅ (requires HungerBridge)

Build docs developers (and LLMs) love

Get started for freeTalk to us