stormlog.infer.vllm_scraper

Scrape vLLM’s /metrics during a profile and keep each response whole.

The profiler scrapes at the start and end of every phase and on a cadence inside it. Each scrape becomes one infer.vllm_scrape record on the client’s clock, so no clock alignment is needed to place it against the phase windows. A scrape that fails is recorded as a failure with its reason, never as an empty set of series. Deltas and rates are computed at analysis time, where resets and restarts can be recognised.

Functions

fetch_metrics(url, *, timeout_seconds[, ...])

GET the metrics text; every failure becomes a result, never an exception.

metrics_api_key(endpoint, url, api_key[, ...])

The bearer token for scrapes: the endpoint's, and only on its origin.

resolve_metrics_url(endpoint, requested)

None when scraping is off; auto is the endpoint's origin plus /metrics.

Classes

FetchResult(text, http_status, error, ...)

What one GET of the metrics URL returned, or why it did not.

VllmMetricsScraper(*, url, interval_seconds, ...)

Turn metrics responses into records and remember what they exposed.
stormlog.infer.vllm_scraper.resolve_metrics_url(endpoint, requested)[source]

None when scraping is off; auto is the endpoint’s origin plus /metrics.

Parameters:

  • endpoint (str)

  • requested (str | None)

Return type:

str | None

stormlog.infer.vllm_scraper.metrics_api_key(endpoint, url, api_key, on_warning=None)[source]

The bearer token for scrapes: the endpoint’s, and only on its origin.

A metrics URL on another scheme, host or port is scraped without credentials, so the token given for the inference endpoint never goes anywhere else; the run says so once.

Parameters:

  • endpoint (str)

  • url (str)

  • api_key (str | None)

  • on_warning (Callable[[str], None] | None)

Return type:

str | None

class stormlog.infer.vllm_scraper.FetchResult(text, http_status, error, duration_ms)[source]

Bases: object

What one GET of the metrics URL returned, or why it did not.

Parameters:

  • text (str | None)

  • http_status (int | None)

  • error (str | None)

  • duration_ms (float)

text: str | None
http_status: int | None
error: str | None
duration_ms: float
stormlog.infer.vllm_scraper.fetch_metrics(url, *, timeout_seconds, api_key=None, max_bytes=8388608)[source]

GET the metrics text; every failure becomes a result, never an exception.

The body is read at most max_bytes + 1 bytes far: a longer response is a failed scrape, and the rest of it is never read.

Parameters:

  • url (str)

  • timeout_seconds (float)

  • api_key (str | None)

  • max_bytes (int)

Return type:

FetchResult

class stormlog.infer.vllm_scraper.VllmMetricsScraper(*, url, interval_seconds, timeout_seconds, session_id, run_id, clock_domain, api_key=None, on_warning=None, max_scrape_bytes=8388608, max_scrape_series=20000)[source]

Bases: object

Turn metrics responses into records and remember what they exposed.

Parameters:

  • url (str)

  • interval_seconds (float)

  • timeout_seconds (float)

  • session_id (str)

  • run_id (str)

  • clock_domain (str)

  • api_key (str | None)

  • on_warning (Callable[[str], None] | None)

  • max_scrape_bytes (int)

  • max_scrape_series (int)

scrape(*, marker, case_id=None, phase=None, timeout_seconds=None)[source]

Fetch and parse once, here; the record says what happened either way.

timeout_seconds overrides the scraper’s own for one scrape, for the one taken on the way out of an interrupted run.

Parameters:

  • marker (str)

  • case_id (str | None)

  • phase (str | None)

  • timeout_seconds (float | None)

Return type:

VllmScrapeRecord

async scrape_async(*, marker, case_id=None, phase=None, timeout_seconds=None)[source]

scrape with the fetch on a thread a cancelled caller abandons.

Counting and the record happen back on the loop, so a fetch dropped by cancellation leaves no trace: no counter moves and no record is written for it.

Parameters:

  • marker (str)

  • case_id (str | None)

  • phase (str | None)

  • timeout_seconds (float | None)

Return type:

VllmScrapeRecord

abandoned(*, marker, case_id, phase, observed_at_ns, deadline_seconds)[source]

The record of a scrape given up at an overall deadline.

The fetch itself may still be reading on its thread; its result is dropped, so this failed record is the only trace of the scrape.

Parameters:

  • marker (str)

  • case_id (str | None)

  • phase (str | None)

  • observed_at_ns (int)

  • deadline_seconds (float)

Return type:

VllmScrapeRecord

async interval_loop(*, append, case_id, phase, stop_event)[source]

Scrape every interval until the phase ends; the fetch runs off the loop.

Cancelling the loop while a fetch is in flight abandons that fetch (see scrape_async), so a stop never waits on a silent endpoint.

Parameters:

  • append (Callable[[dict[str, Any]], None])

  • case_id (str)

  • phase (str)

  • stop_event (Event)

Return type:

None

config_record()[source]
Return type:

dict[str, Any]

capability_event(context)[source]

What the engine exposed, as a v2 capability record for the artifact.

supported lists the catalog’s normalized fields, enabled the ones the first successful scrape exposed, and collected repeats enabled once at least one scrape succeeded. An endpoint that never answered is unavailable with empty lists.

Parameters:

context (CorrelationContext)

Return type:

CapabilityEvent