metricway-sdk 0.1.0__tar.gz

metricway_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Tunik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

metricway_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: metricway-sdk
+Version: 0.1.0
+Summary: Async metrics collector SDK for Telegram bots
+Author: Alexander Tunik
+License-Expression: MIT
+Project-URL: Homepage, https://metricway.tech
+Project-URL: Source, https://github.com/urlifeceo/tgmetricks-sdk
+Project-URL: Issues, https://github.com/urlifeceo/tgmetricks-sdk/issues
+Keywords: telegram,aiogram,analytics,metrics
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.8
+Provides-Extra: aiogram
+Requires-Dist: aiogram<4,>=3.0; extra == "aiogram"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# metricway-sdk
+
+Асинхронный SDK для отправки событий Telegram-бота в [metricway](https://metricway.tech). Поддерживает ручную отправку и автоматический сбор из aiogram 3.
+
+## Установка и быстрый старт
+
+Нужен Python 3.10+. Создайте проект в metricway и сохраните токен в переменной окружения `METRICWAY_PROJECT_TOKEN`. Для aiogram-бота установите пакет:
+
+```bash
+python -m pip install "metricway-sdk[aiogram]"
+```
+
+```python
+import asyncio
+import os
+
+from aiogram import Bot, Dispatcher
+from aiogram.filters import CommandStart
+from aiogram.types import Message
+from metricway import MetricsClient, setup_aiogram_metrics
+
+metrics = MetricsClient(
+    api_url="https://metricway.tech",
+    project_token=os.environ["METRICWAY_PROJECT_TOKEN"],
+)
+dp = Dispatcher()
+setup_aiogram_metrics(dp, metrics)
+
+
+@dp.message(CommandStart())
+async def start_command(message: Message) -> None:
+    await message.answer("Привет!")
+
+
+async def on_startup(bot: Bot) -> None:
+    await metrics.start()
+
+
+async def on_shutdown(bot: Bot) -> None:
+    await metrics.close()
+
+
+dp.startup.register(on_startup)
+dp.shutdown.register(on_shutdown)
+
+
+async def main() -> None:
+    bot = Bot(token=os.environ["TELEGRAM_BOT_TOKEN"])
+    try:
+        await dp.start_polling(bot)
+    finally:
+        await bot.session.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`setup_aiogram_metrics` подключают один раз к роутеру. Он учитывает все входящие сообщения и callback-запросы, даже без подходящего обработчика. В таком случае имя обработчика — `unknown`. Для ручной отправки без aiogram установите `metricway-sdk` без дополнения.
+
+## Ручная отправка
+
+Методы `track_*` синхронные: они добавляют запись в очередь, не ожидая сеть.
+
+```python
+metrics.track_event(
+    user_id=123,
+    chat_id=456,
+    handler="trial_started",
+    update_type="trial",
+    payload={"product_id": "pro_month"},
+)
+metrics.track_traffic(user_id=123, start_payload="campaign_a", utm_source="telegram")
+metrics.track_error(
+    user_id=123,
+    error_type="PaymentError",
+    error_message="Payment failed",
+    stack="",
+)
+metrics.track_purchase(
+    user_id=123,
+    amount=990.0,
+    currency="RUB",
+    product_id="pro_month",
+    payment_provider="telegram_payments",
+)
+```
+
+Покупку отправляйте только после подтверждённой оплаты. Конвертации валюты нет.
+
+## Автоматически собираемые данные
+
+| Событие | Передаваемые данные |
+| --- | --- |
+| Сообщение | ID пользователя и чата, имя обработчика, тип обновления, полный текст |
+| Callback | ID пользователя и чата, имя обработчика, тип обновления, callback data |
+| `/start <payload>` | Дополнительная запись трафика со start payload |
+| Ошибка обработчика | Тип, сообщение и полный стек; исключение продолжает распространяться |
+
+**Текст, callback data и стек могут содержать личные данные и секреты.** Проверьте правила обработки данных своего бота перед подключением. Не передавайте пароли, платёжные реквизиты и другие секреты в payload или текстах ошибок. Храните токен проекта только на сервере; SDK передаёт его в заголовке `X-Project-Token` и поле записи, но не печатает в своих логах.
+
+## Доставка и ограничения
+
+Параметры клиента: `batch_size=500`, `flush_interval=3.0`, `max_queue_size=10000`, `max_retries=5`, `shutdown_timeout=10.0`. Батч ограничен 500 записями и 1 МиБ JSON. Ошибки сети, HTTP 429 и 5xx повторяются до пяти раз после первой попытки с возрастающей задержкой; `Retry-After` учитывается до 60 секунд. Остальные 4xx отклоняются сразу. При заполненной очереди новая запись отбрасывается. `close()` пытается отправить остаток до 10 секунд.
+
+Очередь находится **только в памяти**. Сбой процесса, исчерпание повторов или лимитов может привести к потере событий. Успешный HTTP-ответ означает принятие батча collector, но не гарантирует его запись в постоянное хранилище. Для предупреждений включите логгер `metricway`. После `close()` новые записи отбрасываются.
+
+## Диагностика
+
+1. Проверьте токен проекта и вызов `start()` при старте бота.
+2. Проверьте доступность `https://metricway.tech/collector/` с сервера бота.
+3. Посмотрите логи `metricway`: 401 — токен, 429 — ограничение частоты, 413 — размер запроса.
+4. Отправьте `/start test_campaign` и проверьте событие и источник трафика в кабинете.
+
+Разработка описана в [CONTRIBUTING.md](CONTRIBUTING.md). Лицензия — MIT.

metricway_sdk-0.1.0/README.md

@@ -0,0 +1,115 @@
+# metricway-sdk
+
+Асинхронный SDK для отправки событий Telegram-бота в [metricway](https://metricway.tech). Поддерживает ручную отправку и автоматический сбор из aiogram 3.
+
+## Установка и быстрый старт
+
+Нужен Python 3.10+. Создайте проект в metricway и сохраните токен в переменной окружения `METRICWAY_PROJECT_TOKEN`. Для aiogram-бота установите пакет:
+
+```bash
+python -m pip install "metricway-sdk[aiogram]"
+```
+
+```python
+import asyncio
+import os
+
+from aiogram import Bot, Dispatcher
+from aiogram.filters import CommandStart
+from aiogram.types import Message
+from metricway import MetricsClient, setup_aiogram_metrics
+
+metrics = MetricsClient(
+    api_url="https://metricway.tech",
+    project_token=os.environ["METRICWAY_PROJECT_TOKEN"],
+)
+dp = Dispatcher()
+setup_aiogram_metrics(dp, metrics)
+
+
+@dp.message(CommandStart())
+async def start_command(message: Message) -> None:
+    await message.answer("Привет!")
+
+
+async def on_startup(bot: Bot) -> None:
+    await metrics.start()
+
+
+async def on_shutdown(bot: Bot) -> None:
+    await metrics.close()
+
+
+dp.startup.register(on_startup)
+dp.shutdown.register(on_shutdown)
+
+
+async def main() -> None:
+    bot = Bot(token=os.environ["TELEGRAM_BOT_TOKEN"])
+    try:
+        await dp.start_polling(bot)
+    finally:
+        await bot.session.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+`setup_aiogram_metrics` подключают один раз к роутеру. Он учитывает все входящие сообщения и callback-запросы, даже без подходящего обработчика. В таком случае имя обработчика — `unknown`. Для ручной отправки без aiogram установите `metricway-sdk` без дополнения.
+
+## Ручная отправка
+
+Методы `track_*` синхронные: они добавляют запись в очередь, не ожидая сеть.
+
+```python
+metrics.track_event(
+    user_id=123,
+    chat_id=456,
+    handler="trial_started",
+    update_type="trial",
+    payload={"product_id": "pro_month"},
+)
+metrics.track_traffic(user_id=123, start_payload="campaign_a", utm_source="telegram")
+metrics.track_error(
+    user_id=123,
+    error_type="PaymentError",
+    error_message="Payment failed",
+    stack="",
+)
+metrics.track_purchase(
+    user_id=123,
+    amount=990.0,
+    currency="RUB",
+    product_id="pro_month",
+    payment_provider="telegram_payments",
+)
+```
+
+Покупку отправляйте только после подтверждённой оплаты. Конвертации валюты нет.
+
+## Автоматически собираемые данные
+
+| Событие | Передаваемые данные |
+| --- | --- |
+| Сообщение | ID пользователя и чата, имя обработчика, тип обновления, полный текст |
+| Callback | ID пользователя и чата, имя обработчика, тип обновления, callback data |
+| `/start <payload>` | Дополнительная запись трафика со start payload |
+| Ошибка обработчика | Тип, сообщение и полный стек; исключение продолжает распространяться |
+
+**Текст, callback data и стек могут содержать личные данные и секреты.** Проверьте правила обработки данных своего бота перед подключением. Не передавайте пароли, платёжные реквизиты и другие секреты в payload или текстах ошибок. Храните токен проекта только на сервере; SDK передаёт его в заголовке `X-Project-Token` и поле записи, но не печатает в своих логах.
+
+## Доставка и ограничения
+
+Параметры клиента: `batch_size=500`, `flush_interval=3.0`, `max_queue_size=10000`, `max_retries=5`, `shutdown_timeout=10.0`. Батч ограничен 500 записями и 1 МиБ JSON. Ошибки сети, HTTP 429 и 5xx повторяются до пяти раз после первой попытки с возрастающей задержкой; `Retry-After` учитывается до 60 секунд. Остальные 4xx отклоняются сразу. При заполненной очереди новая запись отбрасывается. `close()` пытается отправить остаток до 10 секунд.
+
+Очередь находится **только в памяти**. Сбой процесса, исчерпание повторов или лимитов может привести к потере событий. Успешный HTTP-ответ означает принятие батча collector, но не гарантирует его запись в постоянное хранилище. Для предупреждений включите логгер `metricway`. После `close()` новые записи отбрасываются.
+
+## Диагностика
+
+1. Проверьте токен проекта и вызов `start()` при старте бота.
+2. Проверьте доступность `https://metricway.tech/collector/` с сервера бота.
+3. Посмотрите логи `metricway`: 401 — токен, 429 — ограничение частоты, 413 — размер запроса.
+4. Отправьте `/start test_campaign` и проверьте событие и источник трафика в кабинете.
+
+Разработка описана в [CONTRIBUTING.md](CONTRIBUTING.md). Лицензия — MIT.

metricway_sdk-0.1.0/metricway/__init__.py

@@ -0,0 +1,20 @@
+from metricway.client import MetricsClient
+
+__all__ = ["MetricsClient", "AiogramMetricsMiddleware", "setup_aiogram_metrics"]
+
+
+def __getattr__(name: str):
+    if name in {"AiogramMetricsMiddleware", "setup_aiogram_metrics"}:
+        try:
+            from metricway.middleware import AiogramMetricsMiddleware, setup_aiogram_metrics
+        except ModuleNotFoundError as exc:
+            if exc.name == "aiogram":
+                raise ModuleNotFoundError(
+                    "aiogram integration requires: pip install 'metricway-sdk[aiogram]'"
+                ) from exc
+            raise
+        return {
+            "AiogramMetricsMiddleware": AiogramMetricsMiddleware,
+            "setup_aiogram_metrics": setup_aiogram_metrics,
+        }[name]
+    raise AttributeError(f"module 'metricway' has no attribute {name!r}")

metricway_sdk-0.1.0/metricway/client.py

@@ -0,0 +1,272 @@
+"""Asynchronous, best-effort metrics delivery."""
+
+import asyncio
+import json
+import logging
+import math
+from collections import defaultdict
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import aiohttp
+
+from metricway.models import ErrorDTO, EventDTO, PurchaseDTO, TrafficDTO
+
+logger = logging.getLogger("metricway")
+MAX_BATCH_SIZE = 500
+MAX_REQUEST_BYTES = 1024 * 1024
+TABLES = ("events", "traffic", "errors", "purchases")
+Record = tuple[str, dict[str, Any]]
+
+
+class MetricsClient:
+    """Queue metrics in memory and send them without blocking bot handlers."""
+
+    def __init__(
+        self,
+        api_url: str,
+        project_token: str,
+        batch_size: int = MAX_BATCH_SIZE,
+        flush_interval: float = 3.0,
+        max_queue_size: int = 10_000,
+        max_retries: int = 5,
+        shutdown_timeout: float = 10.0,
+    ) -> None:
+        if not api_url or not api_url.startswith(("https://", "http://")):
+            raise ValueError("api_url must be an HTTP(S) URL")
+        if not project_token:
+            raise ValueError("project_token must not be empty")
+        if not 1 <= batch_size <= MAX_BATCH_SIZE:
+            raise ValueError("batch_size must be between 1 and 500")
+        if flush_interval <= 0 or max_queue_size <= 0 or max_retries < 0:
+            raise ValueError(
+                "flush_interval and max_queue_size must be positive; max_retries cannot be negative"
+            )
+        if shutdown_timeout <= 0:
+            raise ValueError("shutdown_timeout must be positive")
+
+        self.url = api_url.rstrip("/")
+        self.project_token = project_token
+        self.batch_size = batch_size
+        self.flush_interval = flush_interval
+        self.max_retries = max_retries
+        self.shutdown_timeout = shutdown_timeout
+        self._queue: asyncio.Queue[Record] = asyncio.Queue(maxsize=max_queue_size)
+        self._wake = asyncio.Event()
+        self._worker_task: asyncio.Task[None] | None = None
+        self._session: aiohttp.ClientSession | None = None
+        self._inflight_count = 0
+        self._closed = False
+        self._close_lock = asyncio.Lock()
+
+    async def start(self) -> None:
+        """Start the worker. Repeated calls are safe."""
+        if self._closed:
+            raise RuntimeError("MetricsClient cannot be restarted after close()")
+        if self._worker_task is not None:
+            return
+        self._session = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=5))
+        self._worker_task = asyncio.create_task(self._flusher_loop())
+        logger.info("MetricsClient started")
+
+    async def close(self) -> None:
+        """Drain pending records for at most shutdown_timeout seconds."""
+        async with self._close_lock:
+            if self._closed:
+                return
+            self._closed = True
+            if self._worker_task is None:
+                remaining = self._queue.qsize()
+                if remaining:
+                    logger.warning("Discarding %d metrics: client was never started", remaining)
+                return
+
+            self._wake.set()
+            try:
+                await asyncio.wait_for(self._queue.join(), timeout=self.shutdown_timeout)
+            except asyncio.TimeoutError:
+                logger.warning(
+                    "MetricsClient shutdown timed out; %d metrics were not sent",
+                    self._queue.qsize() + self._inflight_count,
+                )
+            finally:
+                self._worker_task.cancel()
+                try:
+                    await self._worker_task
+                except asyncio.CancelledError:
+                    pass
+                if self._session is not None:
+                    await self._session.close()
+                logger.info("MetricsClient closed")
+
+    def track_event(
+        self, user_id: int, chat_id: int, handler: str, update_type: str, payload: dict[str, Any]
+    ) -> None:
+        try:
+            dto = EventDTO.create(
+                self.project_token, user_id, chat_id, handler, update_type, payload
+            )
+        except (TypeError, ValueError):
+            logger.warning("Discarding events metric: payload is not JSON serializable")
+            return
+        self._enqueue("events", dto.to_dict())
+
+    def track_traffic(
+        self,
+        user_id: int,
+        start_payload: str = "",
+        utm_source: str = "",
+        utm_campaign: str = "",
+        referrer: str = "",
+    ) -> None:
+        dto = TrafficDTO.create(
+            self.project_token, user_id, start_payload, utm_source, utm_campaign, referrer
+        )
+        self._enqueue("traffic", dto.to_dict())
+
+    def track_error(
+        self, user_id: int, error_type: str, error_message: str, stack: str = ""
+    ) -> None:
+        dto = ErrorDTO.create(self.project_token, user_id, error_type, error_message, stack)
+        self._enqueue("errors", dto.to_dict())
+
+    def track_purchase(
+        self,
+        user_id: int,
+        amount: float,
+        currency: str = "RUB",
+        product_id: str = "",
+        payment_provider: str = "",
+    ) -> None:
+        dto = PurchaseDTO.create(
+            self.project_token, user_id, amount, currency, product_id, payment_provider
+        )
+        self._enqueue("purchases", dto.to_dict())
+
+    def _enqueue(self, table: str, item: dict[str, Any]) -> None:
+        if self._closed:
+            logger.warning("Discarding %s metric: client is closed", table)
+            return
+        try:
+            body = self._encode([item])
+        except (TypeError, ValueError):
+            logger.warning("Discarding %s metric: record is not JSON serializable", table)
+            return
+        if len(body) > MAX_REQUEST_BYTES:
+            logger.warning("Discarding %s metric: record exceeds collector request limit", table)
+            return
+        try:
+            self._queue.put_nowait((table, item))
+        except asyncio.QueueFull:
+            logger.warning("Discarding %s metric: queue is full", table)
+            return
+        if self._queue.qsize() >= self.batch_size:
+            self._wake.set()
+
+    async def _flusher_loop(self) -> None:
+        while True:
+            try:
+                if not self._closed:
+                    try:
+                        await asyncio.wait_for(self._wake.wait(), timeout=self.flush_interval)
+                    except asyncio.TimeoutError:
+                        pass
+                self._wake.clear()
+                while not self._queue.empty():
+                    await self._flush()
+                if self._closed:
+                    return
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.exception("Unexpected error in metrics flusher")
+                await asyncio.sleep(1)
+
+    async def _flush(self) -> None:
+        grouped: dict[str, list[dict[str, Any]]] = defaultdict(list)
+        count = 0
+        while count < self.batch_size:
+            try:
+                table, item = self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                break
+            grouped[table].append(item)
+            self._inflight_count += 1
+            count += 1
+
+        for table in TABLES:
+            chunk: list[dict[str, Any]] = []
+            for item in grouped[table]:
+                if chunk and len(self._encode([*chunk, item])) > MAX_REQUEST_BYTES:
+                    await self._finish_batch(table, chunk)
+                    chunk = []
+                chunk.append(item)
+            if chunk:
+                await self._finish_batch(table, chunk)
+
+    async def _finish_batch(self, table: str, items: list[dict[str, Any]]) -> None:
+        try:
+            await self._send_batch(table, items)
+        finally:
+            for _ in items:
+                self._queue.task_done()
+            self._inflight_count -= len(items)
+
+    async def _send_batch(self, table: str, items: list[dict[str, Any]]) -> None:
+        assert self._session is not None
+        endpoint = f"{self.url}/collector/track/{table}"
+        body = self._encode(items)
+        headers = {"Content-Type": "application/json", "X-Project-Token": self.project_token}
+        for attempt in range(self.max_retries + 1):
+            retry_after = 0.0
+            try:
+                async with self._session.post(endpoint, data=body, headers=headers) as response:
+                    if 200 <= response.status < 300:
+                        return
+                    if response.status == 429 or response.status >= 500:
+                        retry_after = self._retry_after(response.headers.get("Retry-After"))
+                    else:
+                        logger.error(
+                            "Discarding %d %s metrics: collector returned HTTP %d",
+                            len(items),
+                            table,
+                            response.status,
+                        )
+                        return
+                    status = f"HTTP {response.status}"
+            except (aiohttp.ClientError, asyncio.TimeoutError, OSError) as exc:
+                status = type(exc).__name__
+
+            if attempt == self.max_retries:
+                logger.error(
+                    "Discarding %d %s metrics after %d attempts (%s)",
+                    len(items),
+                    table,
+                    attempt + 1,
+                    status,
+                )
+                return
+            await asyncio.sleep(max(min(2**attempt, 60), retry_after))
+
+    @staticmethod
+    def _encode(items: list[dict[str, Any]]) -> bytes:
+        return json.dumps(items, separators=(",", ":"), ensure_ascii=False, allow_nan=False).encode(
+            "utf-8"
+        )
+
+    @staticmethod
+    def _retry_after(value: str | None) -> float:
+        if not value:
+            return 0.0
+        try:
+            seconds = float(value)
+        except ValueError:
+            try:
+                date = parsedate_to_datetime(value)
+                seconds = (date - datetime.now(timezone.utc)).total_seconds()
+            except (TypeError, ValueError, OverflowError):
+                return 0.0
+        if not math.isfinite(seconds):
+            return 0.0
+        return min(max(seconds, 0.0), 60.0)

metricway_sdk-0.1.0/metricway/middleware.py

@@ -0,0 +1,93 @@
+"""Optional aiogram 3 integration."""
+
+import traceback
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from aiogram import BaseMiddleware, Router
+from aiogram.types import CallbackQuery, Message, TelegramObject
+
+from metricway.client import MetricsClient
+
+Handler = Callable[[TelegramObject, dict[str, Any]], Awaitable[Any]]
+_CONTEXT_KEY = "_metricway_context"
+
+
+@dataclass
+class _EventContext:
+    handler: str = "unknown"
+
+
+class AiogramMetricsMiddleware(BaseMiddleware):
+    """Outer middleware for message and callback observers."""
+
+    def __init__(self, metrics_client: MetricsClient) -> None:
+        super().__init__()
+        self.client = metrics_client
+
+    async def __call__(self, handler: Handler, event: TelegramObject, data: dict[str, Any]) -> Any:
+        user_id = 0
+        chat_id = 0
+        update_type = "unknown"
+        payload: dict[str, Any] = {}
+
+        if isinstance(event, Message):
+            update_type = "message"
+            user_id = event.from_user.id if event.from_user else 0
+            chat_id = event.chat.id
+            payload["text"] = event.text or ""
+            parts = (event.text or "").split(maxsplit=1)
+            if parts and parts[0].split("@", 1)[0] == "/start" and len(parts) > 1:
+                payload["start_payload"] = parts[1]
+                if user_id:
+                    self.client.track_traffic(user_id=user_id, start_payload=parts[1])
+        elif isinstance(event, CallbackQuery):
+            update_type = "callback_query"
+            user_id = event.from_user.id
+            chat_id = event.message.chat.id if event.message else 0
+            payload["callback_data"] = event.data or ""
+
+        context = _EventContext()
+        data[_CONTEXT_KEY] = context
+        try:
+            return await handler(event, data)
+        except Exception as exc:
+            if user_id:
+                self.client.track_error(
+                    user_id=user_id,
+                    error_type=type(exc).__name__,
+                    error_message=str(exc),
+                    stack=traceback.format_exc(),
+                )
+            raise
+        finally:
+            if user_id:
+                self.client.track_event(
+                    user_id=user_id,
+                    chat_id=chat_id,
+                    handler=context.handler,
+                    update_type=update_type,
+                    payload=payload,
+                )
+
+
+class _HandlerNameMiddleware(BaseMiddleware):
+    """Inner middleware sees the handler resolved by aiogram's filters."""
+
+    async def __call__(self, handler: Handler, event: TelegramObject, data: dict[str, Any]) -> Any:
+        context = data.get(_CONTEXT_KEY)
+        handler_obj = data.get("handler")
+        if context is not None and handler_obj is not None:
+            callback = getattr(handler_obj, "callback", None)
+            if callback is not None:
+                context.handler = getattr(callback, "__name__", "unknown")
+        return await handler(event, data)
+
+
+def setup_aiogram_metrics(router: Router, client: MetricsClient) -> None:
+    """Register metrics for all messages and callbacks on a router."""
+    router.message.outer_middleware(AiogramMetricsMiddleware(client))
+    router.callback_query.outer_middleware(AiogramMetricsMiddleware(client))
+    router.message.middleware(_HandlerNameMiddleware())
+    router.callback_query.middleware(_HandlerNameMiddleware())