Improve framework logging and diagnostics context

[iriswolf]

Source feedback

A user reviewing the alpha said logs should be improved. Multiple conversations also showed that production users will ask what failed, which handler ran, and why an update was skipped or rejected.

Current state

TeleFlow has middleware and transport logs, but the logging contract needs a deliberate audit before 1.0 so diagnostics feel enterprise-ready and consistent.

Target state

Define stable logging events and diagnostic context for update processing, routing, filters, middleware, handlers, callbacks, Telegram client calls, rate limits, and exception paths.

Acceptance criteria

• The audit lists current log events and missing runtime scenarios.
• Logs include useful context without leaking bot tokens, callback payload secrets, or user-provided sensitive data by default.
• Event IDs and message templates are stable enough for production log search.
• Handler failures, Telegram API failures, routing misses, filter rejections, and rate-limit rejections have clear log semantics.
• Tests cover log emission for critical failure paths where practical.
• EN/RU docs include a logging guide and production recommendations.

Non-goals

• Do not build full OpenTelemetry here; that is tracked separately.
• Do not add noisy per-update logs that make production logs unusable by default.

[iriswolf]

Implementation design

This should be treated as a runtime diagnostics contract task, not as a cosmetic logging pass.

Decisions

• TeleFlow remains a Microsoft.Extensions.Logging event emitter. It does not introduce a custom logging provider, sink, or logging engine.
• Event ids are stable within a logger category. They are not a global numeric registry across the whole solution.
• Successful per-update diagnostics stay at Debug. Information is reserved for lifecycle-level events.
• Sensitive payloads are not logged by default.
• Rate-limit rejection must be represented as a normal decision, not as exception-based control flow.

Logging levels

• Information: lifecycle events, for example polling started, connected, stopped, and coarse runtime status.
• Debug: per-update and routing diagnostics, handler matched/completed, no handler matched, timing, request start/completion, filter rejections.
• Warning: recoverable or expected runtime rejections, for example retry-after, callback data deserialization failure, webhook invalid payload/secret, rate-limit rejection.
• Error: unhandled handler failures, Telegram API request failures, update processing failures.

Cancellation through the requested cancellation token should not be logged as an error.

Logging security and privacy model

TeleFlow is not a logging engine. It emits diagnostic events through application-owned Microsoft.Extensions.Logging providers.

Framework logs must use static framework-owned message templates. User-controlled strings must not become logging templates or be evaluated/executed by TeleFlow logging code.

By default TeleFlow must not log:

• bot tokens;
• webhook secrets;
• raw callback data;
• request bodies;
• message text;
• message captions;
• arbitrary rate-limit keys;
• arbitrary user-provided values.

Safe framework metadata can include update id, update type, handler, route, module, scene, exception type, HTTP status code, Telegram method name, retry-after, limiter type, and developer-controlled policy names.

This explicitly keeps Log4Shell-style behavior out of the framework model: TeleFlow does not execute, evaluate, or perform lookup operations on log content.

Rate limiter contract

The current IUpdateRateLimiter.WaitAsync contract is too narrow. It can express waiting, but not a clean rejection.

Do not introduce UpdateRateLimitRejectedException. Rate-limit rejection is an expected runtime decision, not an exceptional failure.

Target shape:

public interface IUpdateRateLimiter
{
    ValueTask<UpdateRateLimitDecision> CheckAsync(
        UpdateContext context,
        CancellationToken cancellationToken = default);
}

public readonly record struct UpdateRateLimitDecision
{
    public static UpdateRateLimitDecision Accepted { get; }

    public static UpdateRateLimitDecision Rejected(
        TimeSpan? retryAfter = null,
        string? policyName = null);

    public bool IsAccepted { get; }

    public TimeSpan? RetryAfter { get; }

    public string? PolicyName { get; }
}

Middleware behavior:

• accepted decision continues the pipeline;
• rejected decision logs a Warning and does not call next;
• limiter exceptions still propagate as real failures;
• if a limiter wants to wait, it waits inside CheckAsync and returns Accepted.

Fast-path requirements

Accepted path must avoid:

• exception control flow;
• string building for diagnostics;
• serialization/deserialization for diagnostics;
• reading message text, captions, or callback data for diagnostics;
• callback payload unpacking for diagnostics;
• unnecessary allocations beyond the existing limiter collection.

Use ValueTask and a value-type decision for cheap synchronous accepts.

Core versus Telegram boundaries

TeleFlow.Framework.Core remains transport-agnostic.

Core rate-limit logging may include payload type, limiter type, retry-after, and policy name. It must not depend on Telegram update id, chat id, user id, message text, or callback data.

Telegram-specific diagnostics belong in the Telegram framework/client/webhook/long-polling packages.

Missing runtime diagnostics to add

• Test logging infrastructure should record EventId so stable events are testable.
• Filter rejections should have Debug diagnostics only after a route matched and filters rejected the candidate.
• Webhook invalid secret and invalid payload should be logged safely without secrets or request bodies.
• Webhook processing failures should carry safe Telegram context when the update was parsed.
• Request failure diagnostics should be audited for stable event ids and safe searchable metadata.

Documentation

Update EN/RU documentation with:

• logging level semantics;
• production recommendations;
• sensitive-data rules;
• rate-limit decision behavior;
• guidance for enabling Debug diagnostics during investigations.

Acceptance criteria

• Rate-limit rejection is result-based, not exception-based.
• Rejected updates stop the pipeline without being logged as errors.
• Fast path avoids diagnostic overhead when Debug is disabled and decisions are accepted.
• Event ids for critical logs are covered by tests.
• Representative tests prove framework logs do not include tokens, webhook secrets, raw callback data, request bodies, message text, or captions by default.
• EN/RU docs describe the logging contract and production usage.