Prombed Python

The Python implementation provides zero-runtime-dependency Prometheus text exposition parsing, bounded in-memory storage, static-target scraping, and PromQL queries. It requires Python 3.10+.

Development

cd <repo_root>/python
uv sync --extra dev
uv run pytest -q
uv run ruff format .
uv run ruff check .

API

from prombed import Prombed, ScrapeTarget

metrics = Prombed(
    targets=[
        ScrapeTarget(
            "http://example:8080/metrics",
            labels={"service": "example"},
            metric_names=("example_requests_total", "example_duration_seconds"),
        )
    ],
    retention_ms=10 * 60_000,
    scrape_interval_ms=5_000,
)

await metrics.start()
success_rate = metrics.query(
    'sum(rate(example_requests_total{status="success"}[1m])) '
    "/ sum(rate(example_requests_total[1m]))"
)
latency = metrics.query(
    "histogram_quantile(0.95, sum by (le) (rate(example_duration_seconds_bucket[1m])))"
)
metrics.stop()

• await scrape_once() scrapes configured targets immediately.
• await start() performs an initial scrape and starts periodic collection; stop() stops it.
• ingest() accepts a snapshot when the caller owns the sampling lifecycle.
• targets() returns target health and the latest scrape error.
• query() and query_range() return Prometheus HTTP API-style dictionaries.

Storage, queries, and external requests have explicit capacity and timeout limits. See the PromQL compatibility contract for supported behavior and deliberate omissions.