pyfect-dev 0.1.0__py3-none-any.whl

pyfect/metric/_metric.py

@@ -0,0 +1,302 @@
+"""The ``Metric`` type: a named, attributed measurement whose series live
+in the ``MetricRegistry`` of the fiber that updates it.
+
+A metric is a description, like an effect: two metrics with the same
+kind, id, description and attributes share one series. Each update looks
+the series up in the current registry, with the current contextual
+attributes merged in, so one metric can feed many registries and many
+attribute sets.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, Final, Generic, Self, TypeVar, final
+
+from pyfect._core import Effect
+from pyfect.context import Context
+from pyfect.exit import Success
+from pyfect.metric._refs import (
+    Attributes,
+    CurrentMetricAttributes,
+    Hooks,
+    Metadata,
+    MetricKey,
+    MetricRegistry,
+    Registry,
+    make_key,
+    merge,
+    to_record,
+)
+
+if TYPE_CHECKING:
+    from pyfect._effect_base import Step
+    from pyfect._fiber import Fiber
+    from pyfect.metric._state import MetricType
+
+In_contra = TypeVar("In_contra", contravariant=True)
+State_co = TypeVar("State_co", covariant=True)
+
+
+class Metric(ABC, Generic[In_contra, State_co]):
+    """A metric taking ``In`` updates and holding a ``State``. Make one
+    with ``metric.counter``, ``gauge``, ``frequency``, ``histogram``,
+    ``summary`` or ``timer``."""
+
+    __slots__ = ("attributes", "description", "id", "type")
+
+    def __init__(
+        self,
+        kind: MetricType,
+        id: str,
+        description: str | None,
+        attributes: Mapping[str, str] | None,
+    ) -> None:
+        self.type: Final[MetricType] = kind
+        self.id: Final = id
+        self.description: Final = description
+        self.attributes: Final = attributes
+
+    @abstractmethod
+    def value_unsafe(self, context: Context) -> State_co:
+        """The state of the series ``context`` selects."""
+
+    @abstractmethod
+    def update_unsafe(self, input: In_contra, context: Context) -> None:
+        """Update the series ``context`` selects."""
+
+    @abstractmethod
+    def modify_unsafe(self, input: In_contra, context: Context) -> None:
+        """Modify the series ``context`` selects (a gauge adds ``input``;
+        the other kinds update)."""
+
+    @abstractmethod
+    def remove_unsafe(self, context: Context) -> None:
+        """Drop the series ``context`` selects from its registry."""
+
+    @abstractmethod
+    def _register(self, context: Context, get: Callable[[Context], Any]) -> Registration: ...
+
+    def value(self) -> Effect[State_co]:
+        """The state of this metric's series in the current registry."""
+        return WithContext(self.value_unsafe)
+
+    def update(self, input: In_contra) -> Effect[None]:
+        """Update the series: a counter adds, a gauge sets, a frequency
+        counts the word, a histogram or summary records the value."""
+        return WithContext(lambda context: self.update_unsafe(input, context))
+
+    def modify(self, input: In_contra) -> Effect[None]:
+        """Modify the series: a gauge adds ``input`` to its value; the
+        other kinds update."""
+        return WithContext(lambda context: self.modify_unsafe(input, context))
+
+    def remove(self) -> Effect[None]:
+        """Drop the series for the current attributes; the next update
+        starts it afresh."""
+        return WithContext(self.remove_unsafe)
+
+    def map_input[In2](self, f: Callable[[In2], In_contra]) -> Metric[In2, State_co]:
+        """The same series, updated with ``f(input)``."""
+        return _Transform(self, lambda input, _: f(input), _same)
+
+    def with_constant_input(self, input: In_contra) -> Metric[object, State_co]:
+        """The same series, updated with ``input`` whatever it is given."""
+        return _Transform(self, lambda _, __: input, _same)
+
+    def with_attributes(self, attributes: Attributes) -> Metric[In_contra, State_co]:
+        """The series with ``attributes`` added; they win over the
+        contextual attributes and the metric's own."""
+        return _Transform(self, _pass_input, _adding(attributes))
+
+    def pipe[B](self, f: Callable[[Self], B], /) -> B:
+        return f(self)
+
+
+def register_unsafe[S](
+    metric: Metric[Any, S], context: Context, get: Callable[[Context], S]
+) -> Registration:
+    """Make ``get`` the series ``context`` selects: snapshots and values
+    call it, updates do nothing. ``remove()`` on the result drops the
+    series, unless something registered it again since."""
+    return metric._register(context, get)
+
+
+@final
+class Registration:
+    __slots__ = ("_key", "_metadata", "_registry")
+
+    def __init__(self, registry: Registry, key: MetricKey, metadata: Metadata) -> None:
+        self._registry = registry
+        self._key = key
+        self._metadata = metadata
+
+    def remove(self) -> None:
+        if self._registry.get(self._key) is self._metadata:
+            del self._registry[self._key]
+
+
+_UNSET: Final[object] = object()
+
+
+class Series(Metric[In_contra, State_co]):
+    """A metric that owns its series: each kind says how a series starts
+    (``_create_hooks``)."""
+
+    __slots__ = ("_cache",)
+
+    def __init__(
+        self,
+        kind: MetricType,
+        id: str,
+        description: str | None,
+        attributes: Attributes | None,
+    ) -> None:
+        super().__init__(kind, id, description, to_record(attributes))
+        # The contextual attributes last seen, and the key and attributes
+        # they give; swapped as one tuple, so a reader never mixes two.
+        self._cache: tuple[object, MetricKey | None, Mapping[str, str] | None] = (
+            _UNSET,
+            None,
+            None,
+        )
+
+    @abstractmethod
+    def _create_hooks(self) -> Hooks: ...
+
+    def value_unsafe(self, context: Context) -> State_co:
+        return self._hooks(context).get(context)
+
+    def update_unsafe(self, input: In_contra, context: Context) -> None:
+        self._hooks(context).update(input, context)
+
+    def modify_unsafe(self, input: In_contra, context: Context) -> None:
+        self._hooks(context).modify(input, context)
+
+    def remove_unsafe(self, context: Context) -> None:
+        key, _ = self._series(context)
+        context.get_unsafe(MetricRegistry).pop(key, None)
+
+    def _register(self, context: Context, get: Callable[[Context], Any]) -> Registration:
+        key, attributes = self._series(context)
+        # The registry of registration time, so removing does not depend
+        # on where ``remove`` is called.
+        registry = context.get_unsafe(MetricRegistry)
+        metadata = self._metadata(attributes, Hooks(get, _ignore, _ignore))
+        registry[key] = metadata
+        return Registration(registry, key, metadata)
+
+    def _hooks(self, context: Context) -> Hooks:
+        # The registry owns the series, so it is looked up on every update.
+        key, attributes = self._series(context)
+        registry = context.get_unsafe(MetricRegistry)
+        metadata = registry.get(key)
+        if metadata is None:
+            metadata = registry.setdefault(key, self._metadata(attributes, self._create_hooks()))
+        return metadata.hooks
+
+    def _series(self, context: Context) -> tuple[MetricKey, Mapping[str, str] | None]:
+        """The key and attributes of the series ``context`` selects, merged
+        once per contextual attribute set."""
+        extra = context.get_unsafe(CurrentMetricAttributes)
+        seen, key, attributes = self._cache
+        if extra is not seen or key is None:
+            merged = merge(self.attributes, extra)
+            attributes = merged if extra else self.attributes
+            key = make_key(self.type, self.id, self.description, merged)
+            self._cache = (extra, key, attributes)
+        return key, attributes
+
+    def _metadata(self, attributes: Mapping[str, str] | None, hooks: Hooks) -> Metadata:
+        return Metadata(self.id, self.type, self.description, attributes, hooks)
+
+
+@final
+class _Transform(Metric[In_contra, State_co]):
+    """Another metric's series, reached through a context and input map.
+    Every operation maps the context first and the input second, so
+    ``with_attributes`` addresses the same series for update, remove and
+    register."""
+
+    __slots__ = ("_map_context", "_map_input", "_metric")
+
+    def __init__(
+        self,
+        metric: Metric[Any, Any],
+        map_input: Callable[[Any, Context], Any],
+        map_context: Callable[[Context], Context],
+    ) -> None:
+        super().__init__(metric.type, metric.id, metric.description, metric.attributes)
+        self._metric = metric
+        self._map_input = map_input
+        self._map_context = map_context
+
+    def value_unsafe(self, context: Context) -> State_co:
+        return self._metric.value_unsafe(self._map_context(context))
+
+    def update_unsafe(self, input: In_contra, context: Context) -> None:
+        mapped = self._map_context(context)
+        self._metric.update_unsafe(self._map_input(input, mapped), mapped)
+
+    def modify_unsafe(self, input: In_contra, context: Context) -> None:
+        mapped = self._map_context(context)
+        self._metric.modify_unsafe(self._map_input(input, mapped), mapped)
+
+    def remove_unsafe(self, context: Context) -> None:
+        self._metric.remove_unsafe(self._map_context(context))
+
+    def _register(self, context: Context, get: Callable[[Context], Any]) -> Registration:
+        return self._metric._register(self._map_context(context), get)
+
+
+def map_input_with_context[In2, S](
+    metric: Metric[Any, S], f: Callable[[In2, Context], Any]
+) -> Metric[In2, S]:
+    """``map_input`` with the updating fiber's context (the summary's
+    clock, say)."""
+    return _Transform(metric, f, _same)
+
+
+def _adding(attributes: Attributes) -> Callable[[Context], Context]:
+    added = to_record(attributes)
+    # Merged once per contextual attribute set, so the wrapped metric
+    # keeps finding its cached series key.
+    cache: tuple[object, Mapping[str, str]] = (_UNSET, {})
+
+    def map_context(context: Context) -> Context:
+        nonlocal cache
+        extra = context.get_unsafe(CurrentMetricAttributes)
+        seen, merged = cache
+        if extra is not seen:
+            merged = merge(extra, added)
+            cache = (extra, merged)
+        return context.add(CurrentMetricAttributes, merged)
+
+    return map_context
+
+
+def _same(context: Context) -> Context:
+    return context
+
+
+def _pass_input(input: Any, _: Context) -> Any:
+    return input
+
+
+def _ignore(_input: Any, _context: Context) -> None:
+    pass
+
+
+@final
+class WithContext[A](Effect[A]):
+    """Run ``f`` with the fiber's context."""
+
+    __slots__ = ("f",)
+
+    def __init__(self, f: Callable[[Context], A]) -> None:
+        self.f = f
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return Success(self.f(fiber._context))

pyfect/metric/_prometheus.py

@@ -0,0 +1,150 @@
+"""The registry in the Prometheus text exposition format (Effect's
+``PrometheusMetrics.format``). ``pyfect.http.prometheus.layer_http`` serves it;
+any other HTTP framework can with the content type
+``text/plain; version=0.0.4; charset=utf-8``."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Callable, Mapping, Sequence
+
+from pyfect._core import Effect
+from pyfect._js import js_number
+from pyfect.context import Context
+from pyfect.metric._metric import WithContext
+from pyfect.metric._snapshot import snapshot_unsafe
+from pyfect.metric._state import (
+    CounterState,
+    FrequencyState,
+    GaugeState,
+    HistogramState,
+    MetricType,
+    Snapshot,
+)
+
+type MetricNameMapper = Callable[[str], str]
+
+_PROMETHEUS_TYPES: Mapping[MetricType, str] = {
+    "Counter": "counter",
+    "Gauge": "gauge",
+    "Histogram": "histogram",
+    "Summary": "summary",
+    "Frequency": "counter",
+}
+_UNEXPORTED_ATTRIBUTES = frozenset(("unit", "time_unit"))
+
+
+def prometheus_format(
+    *, prefix: str | None = None, metric_name_mapper: MetricNameMapper | None = None
+) -> Effect[str]:
+    """The current registry as Prometheus text. Metric names go through
+    ``metric_name_mapper``, are sanitized and get ``prefix_`` in front."""
+    return WithContext(
+        lambda context: prometheus_format_unsafe(
+            context, prefix=prefix, metric_name_mapper=metric_name_mapper
+        )
+    )
+
+
+def prometheus_format_unsafe(
+    context: Context,
+    *,
+    prefix: str | None = None,
+    metric_name_mapper: MetricNameMapper | None = None,
+) -> str:
+    """``prometheus_format`` for ``context``'s registry."""
+    start = _metric_name(prefix) + "_" if prefix else ""
+    families: dict[str, list[Snapshot]] = {}
+    for metric in snapshot_unsafe(context):
+        mapped = metric.id if metric_name_mapper is None else metric_name_mapper(metric.id)
+        families.setdefault(start + _metric_name(mapped), []).append(metric)
+    lines: list[str] = []
+    for name, metrics in families.items():
+        first = metrics[0]
+        if first.description:
+            lines.append(f"# HELP {name} {_escape_help(first.description)}")
+        lines.append(f"# TYPE {name} {_PROMETHEUS_TYPES[first.type]}")
+        for metric in metrics:
+            lines.extend(_samples(name, metric))
+    return "\n".join(lines) + "\n" if lines else ""
+
+
+def _samples(name: str, metric: Snapshot) -> list[str]:
+    attributes = metric.attributes
+    labels = _labels(attributes)
+    match metric.state:
+        case CounterState(count=value) | GaugeState(value=value):
+            return [f"{name}{labels} {_value(value)}"]
+        case FrequencyState(occurrences=occurrences):
+            return [
+                f"{name}{_labels(attributes, [('key', key)])} {count}"
+                for key, count in occurrences.items()
+            ]
+        case HistogramState() as state:
+            lines = [
+                f"{name}_bucket{_labels(attributes, [('le', js_number(b))])} {cumulated}"
+                for b, cumulated in state.buckets
+                if b != math.inf
+            ]
+            lines.append(f"{name}_bucket{_labels(attributes, [('le', '+Inf')])} {state.count}")
+            return [*lines, *_totals(name, labels, state.sum, state.count)]
+        case state:
+            lines = [
+                f"{name}{_labels(attributes, [('quantile', js_number(q))])} {_value(v)}"
+                for q, v in state.quantiles
+                if v is not None
+            ]
+            return [*lines, *_totals(name, labels, state.sum, state.count)]
+
+
+def _totals(name: str, labels: str, total: float, count: int) -> list[str]:
+    return [f"{name}_sum{labels} {_value(total)}", f"{name}_count{labels} {count}"]
+
+
+def _labels(attributes: Mapping[str, str] | None, extra: Sequence[tuple[str, str]] = ()) -> str:
+    pairs = [
+        *(
+            (key, value)
+            for key, value in (attributes or {}).items()
+            if key not in _UNEXPORTED_ATTRIBUTES
+        ),
+        *extra,
+    ]
+    if not pairs:
+        return ""
+    return "{" + ",".join(f'{_label_name(k)}="{_escape_label(v)}"' for k, v in pairs) + "}"
+
+
+def _value(value: float) -> str:
+    if isinstance(value, float) and math.isinf(value):
+        return "+Inf" if value > 0 else "-Inf"
+    return js_number(value)
+
+
+_NOT_METRIC_CHAR = re.compile(r"[^a-zA-Z0-9_:]")
+_NOT_LABEL_CHAR = re.compile(r"[^a-zA-Z0-9_]")
+_UNDERSCORES = re.compile(r"_+")
+
+
+def _metric_name(name: str) -> str:
+    sanitized = _NOT_METRIC_CHAR.sub("_", name)
+    if re.match(r"[0-9:]", sanitized):
+        sanitized = "_" + sanitized
+    sanitized = _UNDERSCORES.sub("_", sanitized)
+    return sanitized.removesuffix("_")
+
+
+def _label_name(name: str) -> str:
+    sanitized = _NOT_LABEL_CHAR.sub("_", name)
+    if re.match(r"[0-9]", sanitized):
+        sanitized = "_" + sanitized
+    return _UNDERSCORES.sub("_", sanitized)
+
+
+def _escape_label(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+def _escape_help(text: str) -> str:
+    return text.replace("\\", "\\\\").replace("\n", "\\n")

pyfect/metric/_refs.py

@@ -0,0 +1,78 @@
+"""The references metrics read: the registry that owns every series, and
+the attributes added to every update in scope."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any
+
+from pyfect.context import Context, Reference
+from pyfect.metric._state import MetricType
+
+type Attributes = Mapping[str, str] | Sequence[tuple[str, str]]
+"""Metric attributes: a mapping, or ``(name, value)`` pairs."""
+
+type MetricKey = tuple[MetricType, str, str | None, tuple[tuple[str, str], ...]]
+"""A series: kind, id, description and the attributes sorted by name."""
+
+
+@dataclass(frozen=True, slots=True)
+class Hooks:
+    """How a series is read and changed. Each takes the updating fiber's
+    context."""
+
+    get: Callable[[Context], Any]
+    update: Callable[[Any, Context], None]
+    modify: Callable[[Any, Context], None]
+
+
+@dataclass(frozen=True, slots=True)
+class Metadata:
+    """A registry entry: the series' identity and its hooks."""
+
+    id: str
+    type: MetricType
+    description: str | None
+    attributes: Mapping[str, str] | None
+    hooks: Hooks
+
+
+type Registry = dict[MetricKey, Metadata]
+
+
+class MetricRegistry(Reference[Registry]):
+    """The series of every metric updated in scope. One process-wide dict
+    by default; provide a fresh ``{}`` to keep metrics apart."""
+
+    @classmethod
+    def default(cls) -> Registry:
+        return {}
+
+
+_NO_ATTRIBUTES: Mapping[str, str] = MappingProxyType({})
+
+
+class CurrentMetricAttributes(Reference[Mapping[str, str]]):
+    """Attributes added to every metric updated in scope. They win over a
+    metric's own attributes; ``with_attributes`` wins over them."""
+
+    @classmethod
+    def default(cls) -> Mapping[str, str]:
+        return _NO_ATTRIBUTES
+
+
+def to_record(attributes: Attributes | None) -> dict[str, str] | None:
+    return None if attributes is None else dict(attributes)
+
+
+def merge(first: Attributes | None, second: Attributes | None) -> dict[str, str]:
+    """``second`` over ``first``; a name keeps the place it first had."""
+    return {**(to_record(first) or {}), **(to_record(second) or {})}
+
+
+def make_key(
+    kind: MetricType, id: str, description: str | None, attributes: Mapping[str, str]
+) -> MetricKey:
+    return (kind, id, description, tuple(sorted(attributes.items())))

pyfect/metric/_runtime.py

@@ -0,0 +1,75 @@
+"""Fiber runtime metrics: counts of fibers started, active, succeeded and
+failed, kept while ``FiberRuntimeMetrics`` is provided."""
+
+from __future__ import annotations
+
+from typing import Any, Final, final
+
+from pyfect._core import Effect
+from pyfect._effect_args import require_effect
+from pyfect._metric_ref import FiberRuntimeMetrics, FiberRuntimeMetricsService
+from pyfect.context import Context
+from pyfect.effect import provide_service
+from pyfect.exit import Exit, Success
+from pyfect.layer import Layer, succeed
+from pyfect.metric._kinds import counter, gauge
+
+_fibers_active = gauge(
+    "child_fibers_active", description="The current count of active child fibers"
+)
+_fibers_started = counter(
+    "child_fibers_started",
+    description="The total number of child fibers that have been started",
+    incremental=True,
+)
+_fiber_successes = counter(
+    "child_fiber_successes",
+    description="The total number of child fibers that have succeeded",
+    incremental=True,
+)
+_fiber_failures = counter(
+    "child_fiber_failures",
+    description="The total number of child fibers that have failed",
+    incremental=True,
+)
+
+
+@final
+class _FiberRuntimeMetrics:
+    __slots__ = ()
+
+    def record_fiber_start(self, context: Context) -> None:
+        _fibers_started.update_unsafe(1, context)
+        _fibers_active.modify_unsafe(1, context)
+
+    def record_fiber_end(self, context: Context, exit: Exit[Any, Any]) -> None:
+        _fibers_active.modify_unsafe(-1, context)
+        if isinstance(exit, Success):
+            _fiber_successes.update_unsafe(1, context)
+        else:
+            _fiber_failures.update_unsafe(1, context)
+
+
+fiber_runtime_metrics: Final[FiberRuntimeMetricsService] = _FiberRuntimeMetrics()
+"""Records into the gauge ``child_fibers_active`` and the counters
+``child_fibers_started``, ``child_fiber_successes`` and
+``child_fiber_failures``."""
+
+enable_runtime_metrics_layer: Final[Layer[FiberRuntimeMetrics]] = succeed(
+    FiberRuntimeMetrics, fiber_runtime_metrics
+)
+disable_runtime_metrics_layer: Final[Layer[FiberRuntimeMetrics]] = succeed(
+    FiberRuntimeMetrics, None
+)
+
+
+def enable_runtime_metrics[A, E, R](eff: Effect[A, E, R]) -> Effect[A, E, R]:
+    """Run ``eff`` recording the fibers it starts in the runtime metrics."""
+    require_effect(eff, "eff")
+    return eff.pipe(provide_service(FiberRuntimeMetrics, fiber_runtime_metrics))
+
+
+def disable_runtime_metrics[A, E, R](eff: Effect[A, E, R]) -> Effect[A, E, R]:
+    """Run ``eff`` without recording fibers."""
+    require_effect(eff, "eff")
+    return eff.pipe(provide_service(FiberRuntimeMetrics, None))