encore-dev 2.0.0a7__py3-none-any.whl

encore/metrics/__init__.py

@@ -0,0 +1,390 @@
+"""Application metrics, declared as module-level variables.
+
+Typical usage example:
+
+    from typing import TypedDict
+
+    from encore import metrics
+
+
+    class ResponseLabels(TypedDict):
+        method: str
+        status: int
+
+
+    requests = metrics.Counter("requests_total")
+    queue_depth = metrics.Gauge("queue_depth")
+    responses = metrics.CounterGroup[ResponseLabels]("responses_total")
+    latency = metrics.Histogram("request_duration", unit="seconds")
+
+    requests.increment()
+    queue_depth.set(3)
+    responses.with_labels({"method": "GET", "status": 200}).increment()
+    latency.observe(0.025)
+
+Declare metrics at module scope and update them with increment(), set(), or
+observe().
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import fields, is_dataclass
+import math
+from threading import Lock
+from typing import Callable, Generic, Union, cast, get_args, overload
+
+from typing_extensions import TypeVar
+
+from ..internal.lazy import Lazy
+from ..internal.runtime import _native, runtime
+
+LabelValue = Union[str, int, float, bool]
+
+
+def _label_pairs(labels: object) -> tuple[tuple[str, str], ...]:
+    if isinstance(labels, Mapping):
+        items = labels.items()
+    elif is_dataclass(labels) and not isinstance(labels, type):
+        items = ((field.name, getattr(labels, field.name)) for field in fields(labels))
+    else:
+        raise TypeError("labels must be a mapping or a dataclass instance")
+    pairs = []
+    for key, value in items:
+        if not isinstance(key, str):
+            raise TypeError("label names must be strings")
+        if isinstance(value, bool):
+            text = "true" if value else "false"
+        elif isinstance(value, float):
+            if not math.isfinite(value):
+                raise ValueError("numeric labels must be finite")
+            text = str(math.floor(value))
+        elif isinstance(value, (str, int)):
+            text = str(value)
+        else:
+            raise TypeError("label values must be strings, booleans, or finite numbers")
+        pairs.append((key, text))
+    return tuple(sorted(pairs))
+
+
+class _MetricBinding:
+    def __init__(
+        self, name: str, kind: _native.MetricType | Callable[[], _native.MetricType]
+    ) -> None:
+        self.name = name
+        self._kind = kind
+        self.labels: tuple[tuple[str, str], ...] = ()
+        self._handle = Lazy(self._resolve)
+
+    def get(self) -> tuple[_native.MetricsRegistry, int]:
+        return self._handle.get()
+
+    def _resolve(self) -> tuple[_native.MetricsRegistry, int]:
+        registry = runtime().get_metrics_registry()
+        kind = self._kind() if callable(self._kind) else self._kind
+        slot = registry.allocate_slot(self.name, list(self.labels), kind)
+        return registry, slot
+
+
+_N = TypeVar("_N", int, float, default=int)
+
+
+def _counter_type(instance: object, index: int) -> type[int] | type[float]:
+    """Resolve a constructor's numeric type after generic metadata is attached."""
+    args = get_args(getattr(instance, "__orig_class__", None))
+    numeric = args[index] if len(args) > index else int
+    if numeric is not int and numeric is not float:
+        raise TypeError("counter numeric type must be int or float")
+    return numeric
+
+
+class Counter(Generic[_N]):
+    """A nondecreasing integer or floating-point counter.
+
+    Counter(name) and Counter[int](name) use unsigned 64-bit integers and wrap
+    on overflow. Counter[float](name) uses double precision and rejects updates
+    that would overflow. Float totals may lose precision, including for integers
+    above 2**53. A variable annotation alone does not select the runtime type.
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a counter at module scope.
+
+        Args:
+            name: The metric name used when exporting measurements.
+        """
+        self._numeric = Lazy(lambda: _counter_type(self, 0))
+        self._binding = _MetricBinding(
+            name,
+            lambda: (
+                _native.MetricType.FloatCounter
+                if self._numeric.get() is float
+                else _native.MetricType.Counter
+            ),
+        )
+
+    @property
+    def name(self) -> str:
+        """The declared metric name."""
+        return self._binding.name
+
+    @overload
+    def increment(self) -> None: ...
+
+    @overload
+    def increment(self, value: _N) -> None: ...
+
+    def increment(self, value: int | float = 1) -> None:
+        """Add a nonnegative amount to the counter.
+
+        Args:
+            value: Defaults to 1. Integer counters require an integer from 0
+                through 2**64 - 1. Float counters accept finite, nonnegative
+                integers or floats.
+
+        Raises:
+            TypeError: The value or constructor's numeric type is unsupported.
+            OverflowError: An integer increment is outside the unsigned range.
+            ValueError: A float increment is negative or nonfinite, its total
+                would overflow, or the series already has a different type.
+        """
+        registry, slot = self._binding.get()
+        if self._numeric.get() is float:
+            registry.increment_float(slot, value)
+        else:
+            registry.increment(slot, cast(int, value))
+
+
+class Gauge:
+    """A gauge that can go up and down."""
+
+    def __init__(self, name: str) -> None:
+        """Declare a gauge at module scope.
+
+        Args:
+            name: The metric name used when exporting measurements.
+        """
+        self._binding = _MetricBinding(name, _native.MetricType.Gauge)
+
+    @property
+    def name(self) -> str:
+        """The declared metric name."""
+        return self._binding.name
+
+    def set(self, value: float) -> None:
+        """Set the gauge's current measurement.
+
+        Args:
+            value: A finite number.
+        """
+        registry, slot = self._binding.get()
+        registry.set(slot, value)
+
+
+class Histogram:
+    """A distribution of observations recorded in automatic exponential buckets.
+
+    Use for measurements such as durations or sizes. The runtime tracks count,
+    sum, and buckets without retaining individual observations. Buckets grow by
+    at most 10% by default and support positive, negative, and zero values.
+
+    Prometheus remote write exports the bucket distribution. Other exporters
+    currently export only the count and sum, which cannot provide percentiles.
+    """
+
+    def __init__(self, name: str, *, unit: str | None = None) -> None:
+        """Declare a histogram at module scope.
+
+        Args:
+            name: The metric name as a string literal.
+            unit: The measurement unit as a string literal, such as "seconds"
+                or "bytes", or None if unspecified. Encore reads this metadata
+                from the declaration; it does not convert observations.
+        """
+        self._binding = _MetricBinding(name, _native.MetricType.Histogram)
+        self._unit = unit
+
+    @property
+    def name(self) -> str:
+        """The declared metric name."""
+        return self._binding.name
+
+    @property
+    def unit(self) -> str | None:
+        """The declared measurement unit, or None if unspecified."""
+        return self._unit
+
+    def observe(self, value: float) -> None:
+        """Record one measurement in the declared unit.
+
+        Args:
+            value: The measurement to record. Prefer finite values. As in the
+                Rust SDK, NaN increments the count and makes the sum NaN but
+                enters no bucket; infinities enter buckets of their own.
+        """
+        registry, slot = self._binding.get()
+        registry.observe(slot, value)
+
+
+_M = TypeVar("_M")
+
+
+class _LabelCache(Generic[_M]):
+    def __init__(self, factory: Callable[[tuple[tuple[str, str], ...]], _M]) -> None:
+        self._factory = factory
+        self._cache: dict[tuple[tuple[str, str], ...], _M] = {}
+        self._lock = Lock()
+
+    def get(self, labels: object) -> _M:
+        pairs = _label_pairs(labels)
+        with self._lock:
+            metric = self._cache.get(pairs)
+            if metric is None:
+                metric = self._factory(pairs)
+                self._cache[pairs] = metric
+            return metric
+
+
+_L = TypeVar("_L")
+
+
+class CounterGroup(Generic[_L, _N]):
+    """A counter partitioned by labels.
+
+    Use a dataclass or TypedDict as the label type. CounterGroup[Labels](name)
+    uses integer counters; CounterGroup[Labels, float](name) uses float counters.
+    Select the numeric type in the constructor, not only a variable annotation.
+    Label values must be strings, booleans, or finite numbers.
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a counter group at module scope.
+
+        Args:
+            name: The metric name used when exporting measurements.
+        """
+        self._name = name
+        self._cache = _LabelCache(self._create_counter)
+
+    @property
+    def name(self) -> str:
+        """The declared metric name."""
+        return self._name
+
+    def with_labels(self, labels: _L) -> Counter[_N]:
+        """Bind labels and reuse the counter for those values.
+
+        Numeric labels are rounded down to integers; booleans become "true"
+        or "false". Label names are normalized to snake_case. The service
+        label is added automatically and cannot be supplied explicitly.
+
+        Args:
+            labels: A dataclass instance or mapping with string, boolean, or
+                finite numeric values. Dataclass fields are read without
+                recursively converting nested objects.
+
+        Returns:
+            The cached counter for this combination of label values.
+        """
+        return self._cache.get(labels)
+
+    def _create_counter(self, pairs: tuple[tuple[str, str], ...]) -> Counter[_N]:
+        counter = (
+            Counter[float](self.name)
+            if _counter_type(self, 1) is float
+            else Counter[int](self.name)
+        )
+        counter._binding.labels = pairs
+        return cast("Counter[_N]", counter)
+
+
+class GaugeGroup(Generic[_L]):
+    """A float gauge partitioned by dataclass or mapping labels."""
+
+    def __init__(self, name: str) -> None:
+        """Declare a gauge group at module scope.
+
+        Args:
+            name: The metric name used when exporting measurements.
+        """
+        self._name = name
+        self._cache = _LabelCache(self._create_gauge)
+
+    @property
+    def name(self) -> str:
+        """The declared metric name."""
+        return self._name
+
+    def with_labels(self, labels: _L) -> Gauge:
+        """Bind labels and reuse the gauge for those values.
+
+        Numeric labels are rounded down to integers; booleans become "true"
+        or "false". Label names are normalized to snake_case. The service
+        label is added automatically and cannot be supplied explicitly.
+
+        Args:
+            labels: A dataclass instance or mapping with string, boolean, or
+                finite numeric values.
+
+        Returns:
+            The cached gauge for this combination of label values.
+        """
+        return self._cache.get(labels)
+
+    def _create_gauge(self, pairs: tuple[tuple[str, str], ...]) -> Gauge:
+        gauge = Gauge(self.name)
+        gauge._binding.labels = pairs
+        return gauge
+
+
+class HistogramGroup(Generic[_L]):
+    """A separate histogram for each combination of label values.
+
+    Use a dataclass or TypedDict as the label type to check names and values.
+    Every series uses the group's unit and the automatic buckets of Histogram.
+    Series remain in memory for the process lifetime, so prefer labels with a
+    small set of possible values, such as operation names, over request IDs.
+    """
+
+    def __init__(self, name: str, *, unit: str | None = None) -> None:
+        """Declare a histogram group at module scope.
+
+        Args:
+            name: The metric name as a string literal.
+            unit: The measurement unit as a string literal, such as "seconds"
+                or "bytes", or None if unspecified. Values are not converted.
+        """
+        self._name = name
+        self._unit = unit
+        self._cache = _LabelCache(self._create_histogram)
+
+    @property
+    def name(self) -> str:
+        """The declared metric name."""
+        return self._name
+
+    @property
+    def unit(self) -> str | None:
+        """The declared measurement unit, or None if unspecified."""
+        return self._unit
+
+    def with_labels(self, labels: _L) -> Histogram:
+        """Bind labels and reuse the histogram for those values.
+
+        Numeric labels are rounded down to integers; booleans become "true"
+        or "false". Label names are normalized to snake_case. The service
+        label is added automatically and cannot be supplied explicitly.
+
+        Args:
+            labels: A dataclass instance or mapping with string, boolean, or
+                finite numeric values.
+
+        Returns:
+            The cached histogram for this combination of label values.
+        """
+        return self._cache.get(labels)
+
+    def _create_histogram(self, pairs: tuple[tuple[str, str], ...]) -> Histogram:
+        histogram = Histogram(self.name, unit=self.unit)
+        histogram._binding.labels = pairs
+        return histogram