waft.metrics.client module

Client for submitting metrics to the WAFT metrics collection worker.

class waft.metrics.client.BatchMetricsPayload(*, metrics: list[MetricPayload], token: str)

Bases: BaseModel

Batch metrics submission payload.

metrics: list[MetricPayload]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

token: str
class waft.metrics.client.MetricPayload(*, type: str, name: str, help: str, value: float | None = None, labels: dict[str, str] = <factory>, buckets: list[float] | None = None)

Bases: BaseModel

Individual metric payload.

buckets: list[float] | None
help: str
labels: dict[str, str]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
type: str
value: float | None
class waft.metrics.client.MetricsClient(worker_url: str, api_token: str, wshim_token: str, timeout: float = 10.0)

Bases: object

Client for submitting metrics to the WAFT metrics collection worker.

This client provides a simple interface for submitting metrics to the Cloudflare Worker that forwards them to Prometheus.

Example

```python client = MetricsClient(

worker_url=”https://waft-metrics-collector.workers.dev”, api_token=”your-api-token”, wshim_token=”your-wshim-token”

)

# Submit a counter client.counter(“test_runs_total”, “Total test runs”, value=1, labels={“status”: “passed”})

# Submit a gauge client.gauge(“test_duration_seconds”, “Test duration”, value=45.2)

# Submit all metrics client.submit() ```

clear() → None

Clear all pending metrics.

counter(name: str, help: str, value: float = 1.0, labels: dict[str, str] | None = None) → None

Add a counter metric to the batch.

Counters are monotonically increasing values (e.g., total requests).

Parameters:

  • name – Metric name

  • help – Metric description

  • value – Counter increment value (default: 1.0)

  • labels – Optional metric labels

Raises:

ValueError – If name/help is empty or value is negative

gauge(name: str, help: str, value: float, labels: dict[str, str] | None = None) → None

Add a gauge metric to the batch.

Gauges are values that can go up or down (e.g., memory usage, duration).

Parameters:

  • name – Metric name

  • help – Metric description

  • value – Current gauge value

  • labels – Optional metric labels

Raises:

ValueError – If name/help is empty

histogram(name: str, help: str, value: float, labels: dict[str, str] | None = None, buckets: list[float] | None = None) → None

Add a histogram metric to the batch.

Histograms are used for bucketed observations (e.g., response times).

Parameters:

  • name – Metric name

  • help – Metric description

  • value – Observed value

  • labels – Optional metric labels

  • buckets – Optional custom buckets (default: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10])

Raises:

ValueError – If name/help is empty

pending_count() → int

Get the number of pending metrics waiting to be submitted.

Returns:

Number of metrics in the queue

submit() → dict[str, Any]

Submit all pending metrics to the worker.

Returns:

Response from the worker containing processing results

Raises:

httpx.HTTPError – If the request fails

submit_single(metric_type: str, name: str, help: str, value: float | None = None, labels: dict[str, str] | None = None, buckets: list[float] | None = None) → dict[str, Any]

Submit a single metric immediately without batching.

Parameters:

  • metric_type – Metric type (counter, gauge, histogram)

  • name – Metric name

  • help – Metric description

  • value – Metric value (defaults to 1.0 for counters, required for gauge/histogram)

  • labels – Optional metric labels

  • buckets – Optional histogram buckets

Returns:

Response from the worker

Raises:

  • ValueError – If metric type is invalid or required value is missing

  • httpx.HTTPError – If the request fails