From fb4b6d0f0c7be36d809a2780267ac07121701ad7 Mon Sep 17 00:00:00 2001 From: ScuroNeko Date: Tue, 31 Mar 2026 13:50:36 +0300 Subject: [PATCH] mark observability model done Move observability from priority backlog to completed framework concepts --- Framework-Backlog-RU.md | 32 ++++++++++++++++++++++++++++---- Framework-Backlog.md | 32 ++++++++++++++++++++++++++++---- 2 files changed, 56 insertions(+), 8 deletions(-) diff --git a/Framework-Backlog-RU.md b/Framework-Backlog-RU.md index 10626d4..bb7f8f1 100644 --- a/Framework-Backlog-RU.md +++ b/Framework-Backlog-RU.md @@ -2,10 +2,6 @@ Эта страница отслеживает список задач уровня фреймворка, связанных с отсутствующими концепциями в библиотеке, а не просто с нехваткой документации. -## Приоритет 1 — Срочно - -- Модель наблюдаемости: логирование уже сильное, но метрики, трассировка и структурированные хуки фреймворка пока не являются полноценной частью API. - ## Приоритет 2 — Важно - Модель сервисного слоя и графа зависимостей: `DatabaseContext(T)` намеренно минималистичен, но нет более сильной концепции уровня фреймворка для сервисов приложения или зависимостей с ограниченной областью действия. @@ -50,6 +46,34 @@ ## Done +### [1.0.0-rc.13] Модель наблюдаемости + +Текущее состояние: + +- Во фреймворке теперь есть полноценная `Observer`-модель с типизированными runtime-событиями и panic-safe dispatch через runtime бота. +- Observer hooks теперь покрывают получение и завершение update-ов, command и payload handlers, generic update handlers, lifecycle сценовых обработчиков, scene transitions, policy checks, завершение runners, polling retries и централизованный error routing. +- Инструментирование остаётся best-effort и не создаёт второй execution pipeline, а также не требует протаскивать app data через observer callbacks. + +Почему это важно: + +- Одного логирования недостаточно, чтобы получить стабильный runtime-facing observability contract для метрик, tracing-адаптеров и структурированного сбора событий. +- Framework-owned hooks делают поведение runtime видимым без необходимости патчить внутренние пути маршрутизации или дублировать инструментирование вокруг команд, payload, сцен и polling. +- Типизированная event model остаётся понятной в godoc и тестах, при этом не перегружая интеграцию observer. + +Что теперь есть: + +- `Observer` как публичный интерфейс инструментирования. +- Типизированные события для update, handler, scene, policy, runner, polling и error flows. +- Безопасный dispatch событий через `safeEmitEvent(...)`, включая recovery от panic. +- Runtime emission в command, payload, generic update и scene flows. +- События проверки политик через `PolicyCheckedEvent`. +- Наблюдаемость runners и polling через `RunnerFinishedEvent`, `PollingRetryEvent` и observer `ErrorEvent`. +- Регрессионные тесты для observer configuration, lifecycle command/payload handlers, lifecycle и transitions сцен, ошибок update handlers, ошибок callback decode, завершения runners, polling retries и policy checks. + +Практическая цель: + +- Считать наблюдаемость полноценной возможностью фреймворка, а не оставлять инструментирование на уровне случайного логирования и внешних обёрток. + ### [1.0.0-rc.13] Модель авторизации и политик Текущее состояние: diff --git a/Framework-Backlog.md b/Framework-Backlog.md index 752dd7b..e4d781f 100644 --- a/Framework-Backlog.md +++ b/Framework-Backlog.md @@ -2,10 +2,6 @@ This page tracks framework-level backlog items that are about missing concepts in the library itself, not just missing documentation. -## Priority 1 — Urgent - -- Observability model: logging is strong, but metrics, tracing, and structured framework hooks are still missing as first-class concepts. - ## Priority 2 — Important - Service layer and dependency graph model: `DatabaseContext(T)` is intentionally minimal, but there is no stronger framework concept for application services or scoped dependencies. @@ -50,6 +46,34 @@ Why this is only partial: ## Done +### [1.0.0-rc.13] Observability Model + +Current state: + +- The framework now exposes a first-class `Observer` model with typed runtime events and a panic-safe dispatch path through the bot runtime. +- Observer hooks now cover update receipt and completion, command and payload handlers, generic update handlers, scene handler lifecycle, scene transitions, policy checks, runner completion, polling retries, and centralized error routing. +- Instrumentation remains best-effort and does not introduce a second execution pipeline or require application data to be threaded through observer callbacks. + +Why this matters: + +- Logging alone is useful, but it does not create a stable runtime-facing observability contract for metrics, tracing adapters, or structured event collection. +- Framework-owned hooks make runtime behavior visible without forcing users to patch internal routing paths or duplicate instrumentation logic around commands, payloads, scenes, and polling. +- A typed event model preserves clarity in godoc and tests while keeping observer integration lightweight. + +What is now present: + +- `Observer` as the public instrumentation interface. +- Typed events for update, handler, scene, policy, runner, polling, and error flows. +- Safe event dispatch through `safeEmitEvent(...)`, including panic recovery. +- Runtime emission across command, payload, generic update, and scene flows. +- Policy evaluation events through `PolicyCheckedEvent`. +- Runner and polling observability through `RunnerFinishedEvent`, `PollingRetryEvent`, and observer `ErrorEvent`s. +- Regression coverage for observer configuration, command and payload lifecycle events, scene lifecycle and transitions, update-handler errors, callback decode failures, runner completion, polling retries, and policy checks. + +Practical target: + +- Treat observability as a first-class framework capability instead of leaving instrumentation to ad-hoc logging and external wrappers. + ### [1.0.0-rc.13] Authorization and Policy Model Current state: