metricway-sdk

Асинхронный SDK для отправки событий Telegram-бота в metricway. Поддерживает ручную отправку и автоматический сбор из aiogram 3.

Установка и быстрый старт

Нужен Python 3.10+. Создайте проект в metricway и сохраните токен в переменной окружения METRICWAY_PROJECT_TOKEN. Для aiogram-бота установите пакет:

python -m pip install "metricway-sdk[aiogram]"

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_* синхронные: они добавляют запись в очередь, не ожидая сеть.

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",
)

Покупку отправляйте только после подтверждённой оплаты. Конвертации валюты нет.

Автоматически собираемые данные

Текст, 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. Лицензия — MIT.