Телеметрия использования: usage_telemetry

Для разработчиков. Состояние на 28.09.2026. Подробности и переменные — README репозитория usage_telemetry. Выкатка коллектора и дашборд лежат в репозитории infra, про него — статья «Мониторинг и автоматизация серверов: infra».

Коротко

usage_telemetry отвечает на вопрос, какими приложениями и какими их разделами пользуются живые люди. Цель — отличить приложение, которое висит мёртвым грузом, от приложения, которым пользуются редко, но по делу, и выключать только первое. Проект состоит из двух частей:

• пакет usage-telemetry: встраивается в приложение одной строкой и считает обращения;
• коллектор: принимает события, складывает их в PostgreSQL и раз в час пересчитывает суточные своды.

Результат смотрят в Grafana, на дашборде «Использование приложений».

приложение (middleware) ──пачками по HTTP──> коллектор ──> PostgreSQL ──> Grafana

Как подключить к проекту

1. Добавить пакет в requirements.txt (или в pyproject.toml), закрепив тег:

   usage-telemetry @ https://github.com/Buharestskie/usage_telemetry/archive/refs/tags/v0.2.0.tar.gz

   Для отправки ошибок в GlitchTip нужен ещё sentry-sdk (extra sentry).
2. Повесить сбор на приложение FastAPI или Starlette:

   from usage_telemetry import install_telemetry
   
   app = FastAPI()
   install_telemetry(app)

   Если задан SENTRY_DSN, install_telemetry заодно инициализирует GlitchTip. Если в проекте SDK уже поднят своим кодом, вызывайте install_telemetry(app, sentry=False).
3. Сообщить, кто пришёл. В зависимости авторизации, где сессия или токен уже разобраны:

   from usage_telemetry import mark_user
   
   mark_user(request, user_id=session.amocrm_user_id, auth="session", session_id=session_id)

   Значения auth: session — человек в браузере; jwt — виджет amoCRM с токеном от widget_auth; telegram — бот или Mini App; basic — админки; api_key — вызов между сервисами; none — без авторизации. Без mark_user вид входа угадывается по заголовкам, но идентификатора пользователя не будет.
4. Для бота на aiogram 3:

   from usage_telemetry import install_bot_telemetry
   
   install_bot_telemetry(dispatcher)

5. Добавить переменные в compose проекта и выкатить в окне обслуживания.

Если не задан TELEMETRY_SERVICE или TELEMETRY_URL, пакет пишет предупреждение в лог и ничего не собирает. Приложение при этом работает как обычно.

Что собирается

Одно событие на одно обращение к приложению:

• Не пишется никогда: строка запроса, тело, referer, имена и почта. В строке запроса ходят разовые токены, а хранилище не должно превращаться в базу утёкших секретов.
• Отсекается на входе: OPTIONS, /health, /healthz, /metrics, /ping, /favicon.ico, /robots.txt, пути под /static/, /assets/, /_next/, /_app/ и файлы статики по расширению. Свои исключения добавляются параметрами skip_paths и skip_prefixes.
• В ботах считаются только входящие от людей: сообщения (команда с короткой меткой вроде /start beeline или тип вложения) и нажатия кнопок. Данные кнопки сводятся к шаблону: service:1842 превращается в service:{id}. Рассылки не считаются, прочтения Telegram ботам не отдаёт.

Как устроено внутри

• Приложение ничего не ждёт. Middleware кладёт событие в очередь в памяти, фоновая задача отправляет пачки в POST /events. Если коллектор недоступен, пачка выбрасывается без повторов. Если очередь переполнилась, она сбрасывается целиком. При остановке приложения остаток отправляется.
• Коллектор — FastAPI с PostgreSQL. Сырые события хранятся в таблице events 90 дней. Раз в час коллектор пересчитывает своды за последние трое суток и чистит устаревшее сырьё. Своды хранятся бессрочно:
  • daily_users — человеко-дни: пара «день + человек». В этот свод попадают только обращения с auth session, jwt, telegram или basic и с известным user_id. Вызовы между сервисами сюда не входят;
  • daily_paths — разделы по дням: число обращений, людей, посетителей по отпечатку, ошибок 5xx и 95-й перцентиль длительности.
• Справочник приложений (таблица services) собирается из status_page_services и telemetry_extra_services в инвентаре infra. Коллектор читает его только при старте. По отметке первого события видно, раскатан ли сбор в приложение.
• Ручки коллектора: POST /events (ответ {"accepted": N}), GET /health, GET /stats — сколько накоплено и когда был последний свод. Коллектор слушает только внутренний интерфейс сервера. С других серверов события идут через путь /telemetry/ на donula26.ru, куда пускают только адреса из списка в роли web_proxy.

Где смотреть

Grafana, grafana.donula26.ru → папка «Инфраструктура» → дашборд «Использование приложений». Период по умолчанию — 30 дней.

Дашборд генерируется скриптом roles/monitoring_server/files/dashboards/generate_usage.py в infra. В браузере он не редактируется.

Выкатка

• Коллектор выкатывается из репозитория infra: ansible-playbook playbooks/telemetry_collector.yml. Роль забирает код из ветки main этого репозитория, выпускает самоподписанный сертификат для базы, один раз создаёт соль отпечатка, раскладывает справочник приложений и поднимает compose. Пароль базы берётся из Vault (telemetry_collector_db_password), без него роль останавливается. База входит в ежедневные бэкапы.
• Пакет приезжает в приложения тегом в зависимостях. Новая версия пакета — это новый тег здесь и правка строки в каждом проекте.
• Проверки: python tests/test_telemetry.py проверяет пакет без базы и сети. COLLECTOR_TEST_DSN=… python collector/tests/test_collector.py проверяет коллектор и требует настоящий PostgreSQL: тест работает в отдельной схеме и удаляет её за собой.

На что наступают

• TELEMETRY_SERVICE не совпал с project в status_page_services. События пишутся, но приложение не попадает в список ожидаемых и на дашборде в таблице живости не видно. Приложениям без пробы на статус-странице код прописывают в telemetry_extra_services.
• После правки справочника в инвентаре коллектор нужно перезапустить. Роль telemetry_collector делает это сама.
• События теряются осознанно. Коллектор лежал — в данных дыра. Приложение, которое молчит, и приложение, которым не пользуются, на сводах выглядят одинаково. Различают их по колонке «Замечание».
• Отпечаток — оценка, а не счёт людей. Сотрудники из офиса сидят за одним адресом, и различает их только user-agent: одинаковые браузеры схлопнутся в одного посетителя.
• Приложение на другом сервере шлёт в пустоту, если адреса этого сервера нет в списке для /telemetry/ в роли web_proxy: nginx отвечает 403, пакет молча выбрасывает события.
• Без привязки к завершению приложения последняя пачка теряется при каждом перезапуске. install_telemetry привязывается к lifespan, а если не получилось, пишет предупреждение в лог. Его не игнорируйте.
• Не у каждого бота есть Dispatcher. У односторонних ботов, которые только рассылают, входящих от людей нет, и мерить там нечего.