argus-dpy 0.2.0__py3-none-any.whl

argus/__init__.py

@@ -0,0 +1,25 @@
+# Argus — discord.py observability SDK
+# Copyright (C) 2026 AstorisTheBrave
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Argus: operational Prometheus/OpenTelemetry metrics for discord.py bots."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"  # x-release-please-version
+
+from argus.cog import Argus, ArgusCog
+
+__all__ = ["Argus", "ArgusCog", "__version__"]

argus/adapters/__init__.py

@@ -0,0 +1,17 @@
+# Argus — discord.py observability SDK
+# Copyright (C) 2026 AstorisTheBrave
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Backend adapters. Each depends on ``core``; ``core`` never depends on these."""

argus/adapters/base.py

@@ -0,0 +1,47 @@
+# Argus — discord.py observability SDK
+# Copyright (C) 2026 AstorisTheBrave
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Adapter ABC: the backend-side contract.
+
+An adapter consumes the neutral registry (it satisfies the core
+:class:`~argus.core.collector.MetricBackend` protocol) and renders it into a
+concrete backend. Defined here so every adapter shares one shape.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+
+from argus.core.collector import MetricDef
+
+
+class Adapter(ABC):
+    @abstractmethod
+    def add_metric(self, metric: MetricDef) -> None:
+        """Register a metric definition with the backend."""
+
+    @abstractmethod
+    def inc(self, name: str, labels: Mapping[str, str] | None = None, amount: float = 1.0) -> None:
+        """Increment a counter."""
+
+    @abstractmethod
+    def observe(self, name: str, value: float, labels: Mapping[str, str] | None = None) -> None:
+        """Record a histogram observation."""
+
+    @abstractmethod
+    def set_info(self, name: str, info: Mapping[str, str]) -> None:
+        """Set the static info labels."""

argus/adapters/prometheus.py

@@ -0,0 +1,99 @@
+# Argus — discord.py observability SDK
+# Copyright (C) 2026 AstorisTheBrave
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Prometheus adapter: one CollectorRegistry, hybrid mechanism (grounding sec.2).
+
+Scrape-time gauges are served by a custom collector that reads the neutral
+gauge callbacks live each scrape (invariant 4). Counters, the duration
+histogram and the info metric are held ``prometheus_client`` objects mutated by
+the event hooks. ``generate_latest`` serialises both together.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+
+from prometheus_client import CONTENT_TYPE_LATEST, CollectorRegistry, Counter, Histogram, Info
+from prometheus_client.core import GaugeMetricFamily
+from prometheus_client.registry import Collector
+
+from argus.adapters.base import Adapter
+from argus.core.collector import MetricDef, MetricKind
+
+__all__ = ["CONTENT_TYPE_LATEST", "PrometheusAdapter"]
+
+
+class _GaugeCollector(Collector):
+    """Reads neutral gauge callbacks at scrape time (invariant 4)."""
+
+    def __init__(self) -> None:
+        self._gauges: list[MetricDef] = []
+
+    def add(self, metric: MetricDef) -> None:
+        self._gauges.append(metric)
+
+    def collect(self) -> Iterator[GaugeMetricFamily]:
+        for metric in self._gauges:
+            family = GaugeMetricFamily(
+                metric.name, metric.documentation, labels=list(metric.labelnames)
+            )
+            if metric.callback is not None:
+                for sample in metric.callback():
+                    family.add_metric(list(sample.labels), sample.value)
+            yield family
+
+
+class PrometheusAdapter(Adapter):
+    def __init__(self, registry: CollectorRegistry | None = None) -> None:
+        self.registry = registry if registry is not None else CollectorRegistry()
+        self._counters: dict[str, Counter] = {}
+        self._histograms: dict[str, Histogram] = {}
+        self._infos: dict[str, Info] = {}
+        self._gauge_collector = _GaugeCollector()
+        self.registry.register(self._gauge_collector)
+
+    def add_metric(self, metric: MetricDef) -> None:
+        labels = list(metric.labelnames)
+        if metric.kind is MetricKind.GAUGE:
+            self._gauge_collector.add(metric)
+        elif metric.kind is MetricKind.COUNTER:
+            self._counters[metric.name] = Counter(
+                metric.name, metric.documentation, labels, registry=self.registry
+            )
+        elif metric.kind is MetricKind.HISTOGRAM:
+            assert metric.buckets is not None  # guaranteed by MetricDef
+            self._histograms[metric.name] = Histogram(
+                metric.name,
+                metric.documentation,
+                labels,
+                buckets=metric.buckets,
+                registry=self.registry,
+            )
+        elif metric.kind is MetricKind.INFO:
+            self._infos[metric.name] = Info(
+                metric.name, metric.documentation, registry=self.registry
+            )
+
+    def inc(self, name: str, labels: Mapping[str, str] | None = None, amount: float = 1.0) -> None:
+        counter = self._counters[name]
+        (counter.labels(**labels) if labels else counter).inc(amount)
+
+    def observe(self, name: str, value: float, labels: Mapping[str, str] | None = None) -> None:
+        histogram = self._histograms[name]
+        (histogram.labels(**labels) if labels else histogram).observe(value)
+
+    def set_info(self, name: str, info: Mapping[str, str]) -> None:
+        self._infos[name].info(dict(info))

argus/cog.py

@@ -0,0 +1,155 @@
+# Argus — discord.py observability SDK
+# Copyright (C) 2026 AstorisTheBrave
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""The public surface: ``ArgusCog`` and the one-line ``Argus(bot)`` convenience.
+
+``ArgusCog`` owns the registry, the Prometheus adapter, the instrumentation and
+the exposition server lifecycle. Listeners are registered synchronously at
+construction (safe before login); ``cog_load`` starts the server on the bot's
+loop and ``cog_unload`` tears everything down (grounding sec.1).
+
+``Argus(bot)`` constructs the cog and chains the bot's ``setup_hook`` so the cog
+is added (and the server started) once the loop is running. The only line a
+user writes is ``Argus(bot)``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from discord.ext import commands
+
+from argus.adapters.prometheus import PrometheusAdapter
+from argus.config import ArgusConfig
+from argus.core.collector import MetricRegistry
+from argus.core.hooks import Registration, register
+from argus.core.instrumentation import Instrumentation
+from argus.core.metrics import bot_info_values, define_metrics
+from argus.history.sink import EventSink, NullSink
+
+log = logging.getLogger("argus")
+
+
+class ArgusCog(commands.Cog):
+    """Holds Argus' state and the exposition server lifecycle."""
+
+    def __init__(self, bot: Any, config: ArgusConfig | None = None) -> None:
+        self.bot = bot
+        self.config = config if config is not None else ArgusConfig.resolve()
+        self.registry = MetricRegistry()
+        self.names = define_metrics(self.registry, bot, self.config)
+        self.adapter = PrometheusAdapter()
+        self.registry.attach(self.adapter)
+        self.sink: EventSink = self._build_sink()
+        self.instrumentation = Instrumentation(
+            self.registry, self.names, self.config, sink=self.sink
+        )
+        self.registry.set_info(self.names.bot_info, bot_info_values())
+        self._runner: Any = None
+        self._analytics_client: Any = None
+        # Register listeners synchronously; additive, safe before the bot logs in.
+        self._registration: Registration = register(bot, self.instrumentation)
+
+    def _build_sink(self) -> EventSink:
+        """Select the analytical sink. NullSink unless per-guild analytics is on."""
+        if self.config.enable_per_guild and self.config.clickhouse_dsn:
+            from argus.history.clickhouse import ClickHouseSink
+
+            return ClickHouseSink(self.config.clickhouse_dsn)
+        return NullSink()
+
+    async def _build_analytics(self) -> Any:
+        """Build the analytics read layer when per-guild analytics is configured."""
+        if not (self.config.enable_per_guild and self.config.clickhouse_dsn):
+            return None
+        import clickhouse_connect  # type: ignore[import-not-found]
+
+        from argus.history.query import AnalyticsQuery
+
+        self._analytics_client = await clickhouse_connect.get_async_client(
+            dsn=self.config.clickhouse_dsn
+        )
+        return AnalyticsQuery(self._analytics_client)
+
+    async def cog_load(self) -> None:
+        from argus import __version__
+        from argus.dashboard.auth import make_auth_middleware
+        from argus.dashboard.server import register_dashboard
+        from argus.exposition.server import build_app, start_server
+
+        dashboard = None
+        middlewares = []
+        if self.config.dashboard:
+            analytics = await self._build_analytics()
+            dashboard = register_dashboard(
+                self.config,
+                registry=self.adapter.registry,
+                version=__version__,
+                analytics=analytics,
+            )
+            if self.config.dashboard_auth_token is not None:
+                middlewares.append(
+                    make_auth_middleware(
+                        self.config.dashboard_auth_token,
+                        frozenset({"/healthz", self.config.metrics_path}),
+                    )
+                )
+
+        app = build_app(
+            self.adapter.registry,
+            self.config.metrics_path,
+            dashboard=dashboard,
+            middlewares=middlewares,
+        )
+        self._runner = await start_server(app, self.config.host, self.config.port)
+        log.info(
+            "argus serving metrics on %s:%d%s",
+            self.config.host,
+            self.config.port,
+            self.config.metrics_path,
+        )
+
+    async def cog_unload(self) -> None:
+        self._registration.remove()
+        if self._runner is not None:
+            await self._runner.cleanup()
+            self._runner = None
+        await self.sink.aclose()
+        if self._analytics_client is not None:
+            await self._analytics_client.close()
+            self._analytics_client = None
+
+
+class Argus:
+    """One-line integration: ``Argus(bot)``.
+
+    Constructs an :class:`ArgusCog` (registering listeners now) and chains the
+    bot's ``setup_hook`` so the cog is added and the metrics server starts once
+    the event loop is running.
+    """
+
+    def __init__(self, bot: Any, **kwargs: Any) -> None:
+        self.config = ArgusConfig.resolve(**kwargs)
+        self.cog = ArgusCog(bot, self.config)
+
+        original_setup_hook = bot.setup_hook
+
+        async def setup_hook(_original: Any = original_setup_hook) -> None:
+            await _original()
+            await bot.add_cog(self.cog)
+
+        bot.setup_hook = setup_hook

argus/config.py

@@ -0,0 +1,161 @@
+# Argus — discord.py observability SDK
+# Copyright (C) 2026 AstorisTheBrave
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""ArgusConfig: the single source of truth for configuration (invariant 6).
+
+Precedence is constructor kwargs over environment variables over defaults. All
+modules read from one resolved :class:`ArgusConfig` instance; no module reads the
+environment or defaults independently.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+# Defaults live here once, so the public API and the env path agree.
+DEFAULT_PORT = 9191
+DEFAULT_HOST = "0.0.0.0"
+DEFAULT_METRICS_PATH = "/metrics"
+DEFAULT_NAMESPACE = "discord"
+DEFAULT_DASHBOARD_PATH = "/"
+DEFAULT_DASHBOARD_INTERVAL = 5
+
+_TRUE = frozenset({"1", "true", "yes", "on"})
+_FALSE = frozenset({"0", "false", "no", "off", ""})
+
+
+def _parse_bool(value: str) -> bool:
+    lowered = value.strip().lower()
+    if lowered in _TRUE:
+        return True
+    if lowered in _FALSE:
+        return False
+    raise ValueError(f"cannot parse {value!r} as a boolean")
+
+
+def _normalize_path(path: str) -> str:
+    return path if path.startswith("/") else "/" + path
+
+
+@dataclass(frozen=True, slots=True)
+class ArgusConfig:
+    """Resolved, immutable configuration.
+
+    Construct via :meth:`resolve`, which applies the kwargs > env > defaults
+    precedence. The dataclass fields are the already-resolved values.
+    """
+
+    port: int = DEFAULT_PORT
+    host: str = DEFAULT_HOST
+    metrics_path: str = DEFAULT_METRICS_PATH
+    cluster_id: str | None = None
+    namespace: str = DEFAULT_NAMESPACE
+    enable_per_guild: bool = False
+    otlp_endpoint: str | None = None
+    dashboard: bool = True
+    dashboard_path: str = DEFAULT_DASHBOARD_PATH
+    dashboard_interval: int = DEFAULT_DASHBOARD_INTERVAL
+    dashboard_auth_token: str | None = None
+    grafana_url: str | None = None
+    clickhouse_dsn: str | None = None
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        port: int | None = None,
+        host: str | None = None,
+        metrics_path: str | None = None,
+        cluster_id: str | None = None,
+        namespace: str | None = None,
+        enable_per_guild: bool | None = None,
+        otlp_endpoint: str | None = None,
+        dashboard: bool | None = None,
+        dashboard_path: str | None = None,
+        dashboard_interval: int | None = None,
+        dashboard_auth_token: str | None = None,
+        grafana_url: str | None = None,
+        clickhouse_dsn: str | None = None,
+        environ: dict[str, str] | None = None,
+    ) -> ArgusConfig:
+        """Build a config from kwargs, falling back to env, then defaults.
+
+        ``None`` for a kwarg means "not provided"; the value is then taken from
+        the matching ``ARGUS_*`` environment variable, and finally the default.
+        ``environ`` is injectable for testing.
+        """
+        env = os.environ if environ is None else environ
+
+        return cls(
+            port=cls._pick_int(port, env.get("ARGUS_PORT"), DEFAULT_PORT),
+            host=cls._pick_str(host, env.get("ARGUS_HOST"), DEFAULT_HOST),
+            metrics_path=_normalize_path(
+                cls._pick_str(metrics_path, env.get("ARGUS_METRICS_PATH"), DEFAULT_METRICS_PATH)
+            ),
+            cluster_id=cls._pick_optional(cluster_id, env.get("ARGUS_CLUSTER_ID")),
+            namespace=cls._pick_str(namespace, env.get("ARGUS_NAMESPACE"), DEFAULT_NAMESPACE),
+            enable_per_guild=cls._pick_bool(
+                enable_per_guild, env.get("ARGUS_ENABLE_PER_GUILD"), False
+            ),
+            otlp_endpoint=cls._pick_optional(otlp_endpoint, env.get("ARGUS_OTLP_ENDPOINT")),
+            dashboard=cls._pick_bool(dashboard, env.get("ARGUS_DASHBOARD"), True),
+            dashboard_path=_normalize_path(
+                cls._pick_str(
+                    dashboard_path, env.get("ARGUS_DASHBOARD_PATH"), DEFAULT_DASHBOARD_PATH
+                )
+            ),
+            dashboard_interval=cls._pick_int(
+                dashboard_interval,
+                env.get("ARGUS_DASHBOARD_INTERVAL"),
+                DEFAULT_DASHBOARD_INTERVAL,
+            ),
+            dashboard_auth_token=cls._pick_optional(
+                dashboard_auth_token, env.get("ARGUS_DASHBOARD_AUTH_TOKEN")
+            ),
+            grafana_url=cls._pick_optional(grafana_url, env.get("ARGUS_GRAFANA_URL")),
+            clickhouse_dsn=cls._pick_optional(clickhouse_dsn, env.get("ARGUS_CLICKHOUSE_DSN")),
+        )
+
+    @staticmethod
+    def _pick_str(kwarg: str | None, env_value: str | None, default: str) -> str:
+        if kwarg is not None:
+            return kwarg
+        if env_value is not None:
+            return env_value
+        return default
+
+    @staticmethod
+    def _pick_optional(kwarg: str | None, env_value: str | None) -> str | None:
+        if kwarg is not None:
+            return kwarg
+        return env_value
+
+    @staticmethod
+    def _pick_int(kwarg: int | None, env_value: str | None, default: int) -> int:
+        if kwarg is not None:
+            return kwarg
+        if env_value is not None:
+            return int(env_value)
+        return default
+
+    @staticmethod
+    def _pick_bool(kwarg: bool | None, env_value: str | None, default: bool) -> bool:
+        if kwarg is not None:
+            return kwarg
+        if env_value is not None:
+            return _parse_bool(env_value)
+        return default

argus/core/__init__.py

@@ -0,0 +1,21 @@
+# Argus — discord.py observability SDK
+# Copyright (C) 2026 AstorisTheBrave
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Argus core: the neutral, backend-agnostic collection layer (invariant 1).
+
+Nothing in this package imports an adapter or a backend client library. Adapters
+depend on ``core``; never the reverse.
+"""

argus/core/collector.py

@@ -0,0 +1,143 @@
+# Argus — discord.py observability SDK
+# Copyright (C) 2026 AstorisTheBrave
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Neutral metric model and registry (invariant 1).
+
+The registry knows metric *definitions* and dispatches mutations to attached
+backends through the :class:`MetricBackend` protocol. It imports no backend
+client library, so adding or removing an adapter can never touch this module.
+
+Three kinds carry all of Argus' signal (grounding sec.2 and sec.4):
+
+* ``GAUGE``     live state, read at scrape time via a callback (invariant 4).
+* ``COUNTER``   monotonic, mutated by event hooks with :meth:`MetricRegistry.inc`.
+* ``HISTOGRAM`` distributions, fed by :meth:`MetricRegistry.observe`.
+* ``INFO``      a single static-label series whose value is always 1.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from types import MappingProxyType
+from typing import Protocol, runtime_checkable
+
+
+class MetricKind(Enum):
+    GAUGE = "gauge"
+    COUNTER = "counter"
+    HISTOGRAM = "histogram"
+    INFO = "info"
+
+
+@dataclass(frozen=True, slots=True)
+class GaugeSample:
+    """One scrape-time gauge reading: label values (in ``labelnames`` order)."""
+
+    labels: tuple[str, ...]
+    value: float
+
+
+# A gauge callback is invoked at scrape time and yields current samples.
+GaugeCallback = Callable[[], Iterable[GaugeSample]]
+
+
+@dataclass(frozen=True, slots=True)
+class MetricDef:
+    """A backend-neutral metric definition."""
+
+    name: str
+    documentation: str
+    kind: MetricKind
+    labelnames: tuple[str, ...] = ()
+    buckets: tuple[float, ...] | None = None  # HISTOGRAM only
+    callback: GaugeCallback | None = None  # GAUGE only
+
+    def __post_init__(self) -> None:
+        if self.kind is MetricKind.HISTOGRAM and self.buckets is None:
+            raise ValueError(f"histogram {self.name!r} requires buckets")
+        if self.kind is MetricKind.GAUGE and self.callback is None:
+            raise ValueError(f"gauge {self.name!r} requires a scrape-time callback")
+        if self.kind is not MetricKind.HISTOGRAM and self.buckets is not None:
+            raise ValueError(f"buckets only valid for a histogram, not {self.name!r}")
+
+
+@runtime_checkable
+class MetricBackend(Protocol):
+    """The seam adapters implement. Defined in core so core imports no adapter."""
+
+    def add_metric(self, metric: MetricDef) -> None:
+        """Register a metric definition with the backend."""
+
+    def inc(self, name: str, labels: Mapping[str, str] | None = None, amount: float = 1.0) -> None:
+        """Increment a counter."""
+
+    def observe(self, name: str, value: float, labels: Mapping[str, str] | None = None) -> None:
+        """Record a histogram observation."""
+
+    def set_info(self, name: str, info: Mapping[str, str]) -> None:
+        """Set the static info labels."""
+
+
+@dataclass(slots=True)
+class MetricRegistry:
+    """Holds metric definitions and fans mutations out to attached backends."""
+
+    _metrics: dict[str, MetricDef] = field(default_factory=dict)
+    _backends: list[MetricBackend] = field(default_factory=list)
+
+    @property
+    def metrics(self) -> Mapping[str, MetricDef]:
+        return MappingProxyType(self._metrics)
+
+    def define(self, metric: MetricDef) -> MetricDef:
+        if metric.name in self._metrics:
+            raise ValueError(f"metric {metric.name!r} already defined")
+        self._metrics[metric.name] = metric
+        for backend in self._backends:
+            backend.add_metric(metric)
+        return metric
+
+    def attach(self, backend: MetricBackend) -> None:
+        """Attach a backend and replay every metric already defined."""
+        self._backends.append(backend)
+        for metric in self._metrics.values():
+            backend.add_metric(metric)
+
+    def inc(self, name: str, labels: Mapping[str, str] | None = None, amount: float = 1.0) -> None:
+        self._require(name, MetricKind.COUNTER)
+        for backend in self._backends:
+            backend.inc(name, labels, amount)
+
+    def observe(self, name: str, value: float, labels: Mapping[str, str] | None = None) -> None:
+        self._require(name, MetricKind.HISTOGRAM)
+        for backend in self._backends:
+            backend.observe(name, value, labels)
+
+    def set_info(self, name: str, info: Mapping[str, str]) -> None:
+        self._require(name, MetricKind.INFO)
+        for backend in self._backends:
+            backend.set_info(name, info)
+
+    def _require(self, name: str, kind: MetricKind) -> MetricDef:
+        try:
+            metric = self._metrics[name]
+        except KeyError:
+            raise KeyError(f"unknown metric {name!r}") from None
+        if metric.kind is not kind:
+            raise TypeError(f"metric {name!r} is {metric.kind.value}, not {kind.value}")
+        return metric