monsta 0.2.0__tar.gz → 0.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {monsta-0.2.0 → monsta-0.2.1}/PKG-INFO +14 -8
- {monsta-0.2.0 → monsta-0.2.1}/README.md +13 -7
- monsta-0.2.1/pyproject.toml +43 -0
- monsta-0.2.0/pyproject.toml → monsta-0.2.1/pyproject.toml.orig +1 -1
- monsta-0.2.1/src/monsta/fields/sliding_window.py +86 -0
- monsta-0.2.0/src/monsta/fields/sliding_window.py +0 -67
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/__init__.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/aiomon.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/fields/__init__.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/fields/base.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/fields/ewma.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/fields/leaky_bucket.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/fields/periodic_sum.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/fields/running_stats.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/fields/sampled_window.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/fields/sliding_percentiles.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/mon.py +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/py.typed +0 -0
- {monsta-0.2.0 → monsta-0.2.1}/src/monsta/state.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: monsta
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.1
|
|
4
4
|
Summary: Simple monitoring REST API for Python applications
|
|
5
5
|
Author: Stefan Schönberger
|
|
6
6
|
Author-email: Stefan Schönberger <stefan@sniner.dev>
|
|
@@ -221,7 +221,7 @@ The lock is reentrant, so you can call `state.to_dict()` from inside a
|
|
|
221
221
|
|
|
222
222
|
| Field | Constructor | Methods | Serialized as |
|
|
223
223
|
|---|---|---|---|
|
|
224
|
-
| `SlidingWindow` | `SlidingWindow(window=60.0)` | `inc`, `set`, `reset`, `+=` | `float` – rate over the window |
|
|
224
|
+
| `SlidingWindow` | `SlidingWindow(window=60.0, buckets=60)` | `inc`, `set`, `reset`, `+=` | `float` – rate over the window |
|
|
225
225
|
| `PeriodicSum` | `PeriodicSum(reset_at=time(0,0), tz=None)` | `inc`, `set`, `reset`, `+=` | `float` – count since last reset |
|
|
226
226
|
| `EWMA` | `EWMA(alpha=0.1, preset=None)` | `update`, `reset` | `float \| None` – current estimate |
|
|
227
227
|
| `RunningStats` | `RunningStats()` | `update`, `reset` | `{"n", "mean", "stddev", "min", "max"}` |
|
|
@@ -235,12 +235,18 @@ Method semantics are uniform across fields: `inc` increments a counter,
|
|
|
235
235
|
There is no method that means "increment on counters but feed sample on
|
|
236
236
|
samplers" – that ambiguity was a 0.1.x footgun and is gone.
|
|
237
237
|
|
|
238
|
-
**`SlidingWindow(window)`** – rate counter. Returns how many
|
|
239
|
-
in the last `window` seconds
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
buckets
|
|
238
|
+
**`SlidingWindow(window, *, buckets=60)`** – rate counter. Returns how many
|
|
239
|
+
hits were recorded in the last `window` seconds. The window is divided into
|
|
240
|
+
`buckets` buckets of `window / buckets` seconds each. A single event counts
|
|
241
|
+
fully for at least `window - window / buckets` seconds and then drops out
|
|
242
|
+
within one bucket, so in a graph it shows up as a rectangle of width `window`.
|
|
243
|
+
A steady rate gives a steady value. More buckets give sharper edges and cost
|
|
244
|
+
one float each. With `buckets=1` the value is a rough estimate: an event
|
|
245
|
+
counts fully only until the next bucket boundary and then fades out over a
|
|
246
|
+
whole `window`. Use `state.x.inc()` (or `state.x += n`) to record events; both
|
|
247
|
+
forms are atomic across threads. `state.x.set(value)` overwrites the current
|
|
248
|
+
bucket (useful for syncing to an external counter). `state.x.reset()` clears
|
|
249
|
+
all buckets.
|
|
244
250
|
|
|
245
251
|
**`PeriodicSum(reset_at=time(0,0), tz=None)`** – calendar-aligned counter that
|
|
246
252
|
accumulates events and snaps back to zero at a configurable wall-clock time
|
|
@@ -209,7 +209,7 @@ The lock is reentrant, so you can call `state.to_dict()` from inside a
|
|
|
209
209
|
|
|
210
210
|
| Field | Constructor | Methods | Serialized as |
|
|
211
211
|
|---|---|---|---|
|
|
212
|
-
| `SlidingWindow` | `SlidingWindow(window=60.0)` | `inc`, `set`, `reset`, `+=` | `float` – rate over the window |
|
|
212
|
+
| `SlidingWindow` | `SlidingWindow(window=60.0, buckets=60)` | `inc`, `set`, `reset`, `+=` | `float` – rate over the window |
|
|
213
213
|
| `PeriodicSum` | `PeriodicSum(reset_at=time(0,0), tz=None)` | `inc`, `set`, `reset`, `+=` | `float` – count since last reset |
|
|
214
214
|
| `EWMA` | `EWMA(alpha=0.1, preset=None)` | `update`, `reset` | `float \| None` – current estimate |
|
|
215
215
|
| `RunningStats` | `RunningStats()` | `update`, `reset` | `{"n", "mean", "stddev", "min", "max"}` |
|
|
@@ -223,12 +223,18 @@ Method semantics are uniform across fields: `inc` increments a counter,
|
|
|
223
223
|
There is no method that means "increment on counters but feed sample on
|
|
224
224
|
samplers" – that ambiguity was a 0.1.x footgun and is gone.
|
|
225
225
|
|
|
226
|
-
**`SlidingWindow(window)`** – rate counter. Returns how many
|
|
227
|
-
in the last `window` seconds
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
buckets
|
|
226
|
+
**`SlidingWindow(window, *, buckets=60)`** – rate counter. Returns how many
|
|
227
|
+
hits were recorded in the last `window` seconds. The window is divided into
|
|
228
|
+
`buckets` buckets of `window / buckets` seconds each. A single event counts
|
|
229
|
+
fully for at least `window - window / buckets` seconds and then drops out
|
|
230
|
+
within one bucket, so in a graph it shows up as a rectangle of width `window`.
|
|
231
|
+
A steady rate gives a steady value. More buckets give sharper edges and cost
|
|
232
|
+
one float each. With `buckets=1` the value is a rough estimate: an event
|
|
233
|
+
counts fully only until the next bucket boundary and then fades out over a
|
|
234
|
+
whole `window`. Use `state.x.inc()` (or `state.x += n`) to record events; both
|
|
235
|
+
forms are atomic across threads. `state.x.set(value)` overwrites the current
|
|
236
|
+
bucket (useful for syncing to an external counter). `state.x.reset()` clears
|
|
237
|
+
all buckets.
|
|
232
238
|
|
|
233
239
|
**`PeriodicSum(reset_at=time(0,0), tz=None)`** – calendar-aligned counter that
|
|
234
240
|
accumulates events and snaps back to zero at a configurable wall-clock time
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "monsta"
|
|
3
|
+
version = "0.2.1"
|
|
4
|
+
description = "Simple monitoring REST API for Python applications"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.10"
|
|
7
|
+
dependencies = [
|
|
8
|
+
"fastapi>=0.133.1",
|
|
9
|
+
"pydantic>=2.12.5",
|
|
10
|
+
"uvicorn>=0.41.0",
|
|
11
|
+
]
|
|
12
|
+
|
|
13
|
+
[[project.authors]]
|
|
14
|
+
name = "Stefan Schönberger"
|
|
15
|
+
email = "stefan@sniner.dev"
|
|
16
|
+
|
|
17
|
+
[build-system]
|
|
18
|
+
requires = ["uv_build>=0.10.6,<0.11.0"]
|
|
19
|
+
build-backend = "uv_build"
|
|
20
|
+
|
|
21
|
+
[dependency-groups]
|
|
22
|
+
dev = [
|
|
23
|
+
"basedpyright>=1.38.2",
|
|
24
|
+
"pytest>=9.0.2",
|
|
25
|
+
"ruff>=0.15.3",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
[tool.pytest.ini_options]
|
|
29
|
+
addopts = "-ra -q"
|
|
30
|
+
testpaths = ["tests"]
|
|
31
|
+
|
|
32
|
+
[tool.pyright]
|
|
33
|
+
typeCheckingMode = "standard"
|
|
34
|
+
useLibraryCodeForTypes = true
|
|
35
|
+
venvPath = "."
|
|
36
|
+
venv = ".venv"
|
|
37
|
+
|
|
38
|
+
[tool.ruff]
|
|
39
|
+
line-length = 96
|
|
40
|
+
ignore = ["E402"]
|
|
41
|
+
|
|
42
|
+
[tool.ruff.lint.per-file-ignores]
|
|
43
|
+
"__init__.py" = ["F401"]
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import threading
|
|
4
|
+
import time
|
|
5
|
+
|
|
6
|
+
from .base import Field
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class SlidingWindow(Field):
|
|
10
|
+
"""Counter over the last ``window`` seconds, useful for rates.
|
|
11
|
+
|
|
12
|
+
The window is divided into ``buckets`` buckets of ``window / buckets``
|
|
13
|
+
seconds each. ``serialize()`` returns the sum of the buckets that cover
|
|
14
|
+
the last ``window`` seconds. The oldest bucket is weighted by the part
|
|
15
|
+
of it that is still inside the window, so a steady rate gives a steady
|
|
16
|
+
value. A single event counts fully for at least ``window - window /
|
|
17
|
+
buckets`` seconds and then drops to zero within one bucket.
|
|
18
|
+
|
|
19
|
+
More buckets make the edges sharper at the cost of one float per
|
|
20
|
+
bucket. ``buckets=1`` gives a coarse estimate: an event counts fully
|
|
21
|
+
only until the next bucket boundary and then fades out over a whole
|
|
22
|
+
``window``.
|
|
23
|
+
|
|
24
|
+
API:
|
|
25
|
+
- ``inc(amount=1.0)`` — atomically add ``amount`` to the current bucket
|
|
26
|
+
- ``state.x += n`` — alias for ``inc(n)``, also atomic
|
|
27
|
+
- ``set(value)`` — overwrite the current bucket (e.g. external sync)
|
|
28
|
+
- ``reset()`` — clear all buckets
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
def __init__(self, window: float = 60.0, *, buckets: int = 60) -> None:
|
|
32
|
+
if window <= 0:
|
|
33
|
+
raise ValueError(f"window must be positive, got {window}")
|
|
34
|
+
if buckets < 1:
|
|
35
|
+
raise ValueError(f"buckets must be at least 1, got {buckets}")
|
|
36
|
+
self.window = window
|
|
37
|
+
self.buckets = buckets
|
|
38
|
+
self._width = window / buckets
|
|
39
|
+
self._lock = threading.Lock()
|
|
40
|
+
# One bucket more than ``buckets``: the oldest one is partly outside
|
|
41
|
+
# the window and still contributes with its remaining fraction.
|
|
42
|
+
self._slots: list[float] = [0.0] * (buckets + 1)
|
|
43
|
+
self._last_idx: int = int(time.monotonic() // self._width)
|
|
44
|
+
|
|
45
|
+
def _sync(self, now: float) -> int:
|
|
46
|
+
idx = int(now // self._width)
|
|
47
|
+
elapsed = idx - self._last_idx
|
|
48
|
+
if elapsed > 0:
|
|
49
|
+
n = len(self._slots)
|
|
50
|
+
for i in range(self._last_idx + 1, self._last_idx + 1 + min(elapsed, n)):
|
|
51
|
+
self._slots[i % n] = 0.0
|
|
52
|
+
self._last_idx = idx
|
|
53
|
+
return idx
|
|
54
|
+
|
|
55
|
+
def inc(self, amount: float = 1.0) -> None:
|
|
56
|
+
with self._lock:
|
|
57
|
+
idx = self._sync(time.monotonic())
|
|
58
|
+
self._slots[idx % len(self._slots)] += float(amount)
|
|
59
|
+
|
|
60
|
+
def set(self, value: float) -> None:
|
|
61
|
+
with self._lock:
|
|
62
|
+
idx = self._sync(time.monotonic())
|
|
63
|
+
self._slots[idx % len(self._slots)] = float(value)
|
|
64
|
+
|
|
65
|
+
def reset(self) -> None:
|
|
66
|
+
with self._lock:
|
|
67
|
+
self._slots = [0.0] * (self.buckets + 1)
|
|
68
|
+
self._last_idx = int(time.monotonic() // self._width)
|
|
69
|
+
|
|
70
|
+
def __iadd__(self, amount: float) -> SlidingWindow:
|
|
71
|
+
self.inc(amount)
|
|
72
|
+
# Returning self is critical: AppState.__setattr__ then sees a
|
|
73
|
+
# Field-to-Field rebind (same instance) and lets it through.
|
|
74
|
+
return self
|
|
75
|
+
|
|
76
|
+
def serialize(self) -> float:
|
|
77
|
+
with self._lock:
|
|
78
|
+
now = time.monotonic()
|
|
79
|
+
idx = self._sync(now)
|
|
80
|
+
# _sync has cleared everything older than ``buckets`` buckets, so
|
|
81
|
+
# the ring holds exactly the current bucket and the ``buckets``
|
|
82
|
+
# before it. The oldest of them sits at idx - buckets, which is
|
|
83
|
+
# idx + 1 modulo the ring size.
|
|
84
|
+
oldest = self._slots[(idx + 1) % len(self._slots)]
|
|
85
|
+
elapsed = (now % self._width) / self._width
|
|
86
|
+
return sum(self._slots) - oldest * elapsed
|
|
@@ -1,67 +0,0 @@
|
|
|
1
|
-
from __future__ import annotations
|
|
2
|
-
|
|
3
|
-
import threading
|
|
4
|
-
import time
|
|
5
|
-
|
|
6
|
-
from .base import Field
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
class SlidingWindow(Field):
|
|
10
|
-
"""Counter that averages a sliding interval, useful for rates.
|
|
11
|
-
|
|
12
|
-
Returns the number of hits accumulated over the last ``window``
|
|
13
|
-
seconds, with smooth interpolation across bucket boundaries. The
|
|
14
|
-
counter has two adjacent buckets internally; ``serialize()`` mixes
|
|
15
|
-
them by the elapsed fraction of the current bucket.
|
|
16
|
-
|
|
17
|
-
API:
|
|
18
|
-
- ``inc(amount=1.0)`` — atomically add ``amount`` to the current bucket
|
|
19
|
-
- ``state.x += n`` — alias for ``inc(n)``, also atomic
|
|
20
|
-
- ``set(value)`` — overwrite the current bucket (e.g. external sync)
|
|
21
|
-
- ``reset()`` — clear both buckets
|
|
22
|
-
"""
|
|
23
|
-
|
|
24
|
-
def __init__(self, window: float = 60.0) -> None:
|
|
25
|
-
if window <= 0:
|
|
26
|
-
raise ValueError(f"window must be positive, got {window}")
|
|
27
|
-
self.window = window
|
|
28
|
-
self._lock = threading.Lock()
|
|
29
|
-
self._prev: float = 0.0
|
|
30
|
-
self._curr: float = 0.0
|
|
31
|
-
self._last_idx: int = int(time.monotonic() // window)
|
|
32
|
-
|
|
33
|
-
def _sync(self, now: float) -> None:
|
|
34
|
-
idx = int(now // self.window)
|
|
35
|
-
if idx > self._last_idx:
|
|
36
|
-
self._prev = self._curr if idx == self._last_idx + 1 else 0.0
|
|
37
|
-
self._curr = 0.0
|
|
38
|
-
self._last_idx = idx
|
|
39
|
-
|
|
40
|
-
def inc(self, amount: float = 1.0) -> None:
|
|
41
|
-
with self._lock:
|
|
42
|
-
self._sync(time.monotonic())
|
|
43
|
-
self._curr += float(amount)
|
|
44
|
-
|
|
45
|
-
def set(self, value: float) -> None:
|
|
46
|
-
with self._lock:
|
|
47
|
-
self._sync(time.monotonic())
|
|
48
|
-
self._curr = float(value)
|
|
49
|
-
|
|
50
|
-
def reset(self) -> None:
|
|
51
|
-
with self._lock:
|
|
52
|
-
self._prev = 0.0
|
|
53
|
-
self._curr = 0.0
|
|
54
|
-
self._last_idx = int(time.monotonic() // self.window)
|
|
55
|
-
|
|
56
|
-
def __iadd__(self, amount: float) -> SlidingWindow:
|
|
57
|
-
self.inc(amount)
|
|
58
|
-
# Returning self is critical: AppState.__setattr__ then sees a
|
|
59
|
-
# Field-to-Field rebind (same instance) and lets it through.
|
|
60
|
-
return self
|
|
61
|
-
|
|
62
|
-
def serialize(self) -> float:
|
|
63
|
-
with self._lock:
|
|
64
|
-
now = time.monotonic()
|
|
65
|
-
self._sync(now)
|
|
66
|
-
weight = max(0.0, min(1.0, (self.window - now % self.window) / self.window))
|
|
67
|
-
return (self._prev * weight) + self._curr
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|