remotivelabs.topology.metrics

1from __future__ import annotations
2
3from remotivelabs.topology.metrics.api import Metric, Metrics, NoOpMetrics, Tags
4from remotivelabs.topology.metrics.runtime import get_metrics
5
6__all__ = ["Metric", "Metrics", "NoOpMetrics", "Tags", "get_metrics"]
class Metric(builtins.str, enum.Enum):
18class Metric(str, Enum):
19    """Names of every metric the library can emit."""
20
21    FRAMES_RECEIVED = "frames.received"
22    HANDLER_DURATION = "handler.duration"

Names of every metric the library can emit.

FRAMES_RECEIVED = <Metric.FRAMES_RECEIVED: 'frames.received'>
HANDLER_DURATION = <Metric.HANDLER_DURATION: 'handler.duration'>
class Metrics(typing.Protocol):
25class Metrics(Protocol):
26    """Sink for metric observations. Backends implement this protocol."""
27
28    def increment(self, metric: Metric, tags: Tags) -> None:
29        """Increment a counter by one."""
30
31    def counter(self, metric: Metric, tags: Tags, value: int) -> None:
32        """Add ``value`` to a counter."""
33
34    def timing(self, metric: Metric, tags: Tags, seconds: float) -> None:
35        """Record a histogram observation in seconds."""
36
37    def timed(self, metric: Metric, tags: Tags) -> AbstractContextManager[None]:
38        """Context manager that records elapsed seconds on exit."""

Sink for metric observations. Backends implement this protocol.

Metrics(*args, **kwargs)
1945def _no_init_or_replace_init(self, *args, **kwargs):
1946    cls = type(self)
1947
1948    if cls._is_protocol:
1949        raise TypeError('Protocols cannot be instantiated')
1950
1951    # Already using a custom `__init__`. No need to calculate correct
1952    # `__init__` to call. This can lead to RecursionError. See bpo-45121.
1953    if cls.__init__ is not _no_init_or_replace_init:
1954        return
1955
1956    # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`.
1957    # The first instantiation of the subclass will call `_no_init_or_replace_init` which
1958    # searches for a proper new `__init__` in the MRO. The new `__init__`
1959    # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent
1960    # instantiation of the protocol subclass will thus use the new
1961    # `__init__` and no longer call `_no_init_or_replace_init`.
1962    for base in cls.__mro__:
1963        init = base.__dict__.get('__init__', _no_init_or_replace_init)
1964        if init is not _no_init_or_replace_init:
1965            cls.__init__ = init
1966            break
1967    else:
1968        # should not happen
1969        cls.__init__ = object.__init__
1970
1971    cls.__init__(self, *args, **kwargs)
def increment( self, metric: Metric, tags: Mapping[str, str]) -> None:
28    def increment(self, metric: Metric, tags: Tags) -> None:
29        """Increment a counter by one."""

Increment a counter by one.

def counter( self, metric: Metric, tags: Mapping[str, str], value: int) -> None:
31    def counter(self, metric: Metric, tags: Tags, value: int) -> None:
32        """Add ``value`` to a counter."""

Add value to a counter.

def timing( self, metric: Metric, tags: Mapping[str, str], seconds: float) -> None:
34    def timing(self, metric: Metric, tags: Tags, seconds: float) -> None:
35        """Record a histogram observation in seconds."""

Record a histogram observation in seconds.

def timed( self, metric: Metric, tags: Mapping[str, str]) -> contextlib.AbstractContextManager[None]:
37    def timed(self, metric: Metric, tags: Tags) -> AbstractContextManager[None]:
38        """Context manager that records elapsed seconds on exit."""

Context manager that records elapsed seconds on exit.

class NoOpMetrics:
41class NoOpMetrics:
42    """Default ``Metrics`` implementation — records nothing."""
43
44    def increment(self, metric: Metric, tags: Tags) -> None:
45        pass
46
47    def counter(self, metric: Metric, tags: Tags, value: int) -> None:
48        pass
49
50    def timing(self, metric: Metric, tags: Tags, seconds: float) -> None:
51        pass
52
53    def timed(self, metric: Metric, tags: Tags) -> AbstractContextManager[None]:  # noqa: ARG002
54        return _noop_context()

Default Metrics implementation — records nothing.

def increment( self, metric: Metric, tags: Mapping[str, str]) -> None:
44    def increment(self, metric: Metric, tags: Tags) -> None:
45        pass
def counter( self, metric: Metric, tags: Mapping[str, str], value: int) -> None:
47    def counter(self, metric: Metric, tags: Tags, value: int) -> None:
48        pass
def timing( self, metric: Metric, tags: Mapping[str, str], seconds: float) -> None:
50    def timing(self, metric: Metric, tags: Tags, seconds: float) -> None:
51        pass
def timed( self, metric: Metric, tags: Mapping[str, str]) -> contextlib.AbstractContextManager[None]:
53    def timed(self, metric: Metric, tags: Tags) -> AbstractContextManager[None]:  # noqa: ARG002
54        return _noop_context()
Tags = typing.Mapping[str, str]
def get_metrics() -> Metrics:
35def get_metrics() -> Metrics:
36    """Return the process-wide ``Metrics`` sink.
37
38    Without ``METRICS_PORT`` set, returns a no-op sink with zero overhead.
39    With ``METRICS_PORT`` set, lazily configures an OpenTelemetry MeterProvider
40    with a Prometheus exporter and serves ``/metrics`` on that port.
41
42    Raises:
43        ValueError: If ``METRICS_PORT`` is not a valid port number.
44
45    Note:
46        By default, enabling metrics unregisters ``prometheus_client``'s
47        default ``python_*``/``process_*``/GC collectors so scrapes contain
48        only application metrics. Set ``METRICS_KEEP_PROMETHEUS_DEFAULTS=1``
49        to keep them.
50    """
51    port = _read_port()
52    if port is None:
53        return _NOOP
54
55    global _metrics  # noqa: PLW0603
56    if _metrics is None:
57        # Lazy import: keeps the opentelemetry/prometheus import cost off the
58        # hot path for processes that never enable metrics.
59        from remotivelabs.topology.metrics._otel import build_otel_metrics  # noqa: PLC0415
60
61        _logger.info("Configuring OpenTelemetry MeterProvider with Prometheus exporter on port %s", port)
62        _metrics = build_otel_metrics(port)
63    return _metrics

Return the process-wide Metrics sink.

Without METRICS_PORT set, returns a no-op sink with zero overhead. With METRICS_PORT set, lazily configures an OpenTelemetry MeterProvider with a Prometheus exporter and serves /metrics on that port.

Raises:
  • ValueError: If METRICS_PORT is not a valid port number.
Note:

By default, enabling metrics unregisters prometheus_client's default python_*/process_*/GC collectors so scrapes contain only application metrics. Set METRICS_KEEP_PROMETHEUS_DEFAULTS=1 to keep them.