Monitoring, Logging & Error Handling
Relevant source files
The following files were used as context for generating this wiki page:
The Monitoring, Logging & Error Handling systems ensure the Telegram History Bot operates reliably within the Cloudflare Workers environment. This module encompasses request validation, privacy-safe logging, automated recovery through fallbacks, and health monitoring. The bot prioritizes data privacy by stripping PII from logs and using secure error boundaries to prevent sensitive information leaks.
Logging Strategy
The bot implements a tiered logging approach that balances operational visibility with strict privacy requirements. It uses a custom Logger utility to categorize events and enforces rules to protect user data and credentials.
Privacy and Security Rules
Developers must follow these logging constraints:
- No PII: Never log full Telegram payloads or user messages. Use
console.debugwith hashed IDs when message tracking is necessary. - Credential Protection: Never print secrets, including
TOKEN,SECRET, or API keys. - Safe Errors: Do not log raw error messages that might embed request payloads. Use the
describeErrorfunction to log only the error class name.
Sources: AGENTS.md:100-105, CLAUDE.md:8-13, src/index.ts:65-72
Logger Operations
The bot utilizes Logger.debug, Logger.info, Logger.warn, and Logger.error to track system state.
The diagram shows the standard logging flow during a Telegram webhook update.
Sources: src/index.ts:260-295
Error Handling Framework
The system handles failures through structured response objects and automated fallback mechanisms. This prevents the exposure of Cloudflare-specific error pages to end-users and ensures service continuity.
Global Error Boundaries
The fetch handler wraps critical sections, such as admin requests, in try-catch blocks. If an unhandled exception occurs in the /admin path, the bot returns a structured JSON response via adminUnavailableResponse.
| Component | Error Code | HTTP Status | User Message |
|---|---|---|---|
| Admin Service | ADMIN_UNAVAILABLE | 503 | Admin service is temporarily unavailable. |
| Analysis | LIVE_ANALYSIS_FAILED | N/A | Анализ текущего дня не завершён |
| Stats | HISTORICAL_STATS_NOT_READY | N/A | Данные пока не готовы |
Sources: src/index.ts:33-47, tests/admin-html.test.ts:133-145
Optimized Summary Fallback
The summary system includes a robust fallback mechanism. If the optimized summary fails due to configuration errors or API quotas, the bot automatically triggers the legacy summarization system.
The sequence shows how the bot maintains service availability by falling back to legacy code when modern optimizations fail.
Sources: README.md:78-85, tests/integration/optimized-summary.test.ts:109-130
Monitoring and Health Checks
Monitoring provides real-time visibility into bot performance and resource utilization.
Configuration for Monitoring
Environment variables control the verbosity of performance tracking and metrics collection.
| Variable | Type | Description |
|---|---|---|
SUMMARY_OPT_ENABLE_DETAILED_METRICS | Boolean | Enables tracking of processing times and worker efficiency. |
SUMMARY_OPT_LOG_PERFORMANCE_INSIGHTS | Boolean | Outputs detailed performance logs to the console. |
SUMMARY_OPT_TRACK_TOKEN_USAGE | Boolean | Monitors AI token consumption per request. |
DEBUG_LOGS | String/Boolean | Toggles detailed debug logging (enabled in development). |
Sources: tests/integration/optimized-summary.test.ts:30-55, tests/index.test.ts:34
Real-time Observation
Administrators monitor live logs using the Cloudflare Wrangler CLI. The bot outputs specific markers to identify the state of the optimized summary system.
- Command:
wrangler tail --format=pretty | grep "Optimized summary" - Key Logs:
Attempting optimized summary: Indicates the system activation.Optimized summary completed successfully: Indicates a successful run.Optimized summary failed, falling back to legacy: Indicates a handled error.
Sources: README.md:75-85
Health Endpoint
The bot exposes a simple /healthz endpoint. It returns an ok response with a 200 status code to verify the Worker is active and reachable.
Sources: src/index.ts:254
Summary of Operational Resilience
The monitoring and error handling architecture ensures that failures are contained and audited without compromising user privacy. By utilizing Cloudflare-native tools like wrangler tail and implementing hierarchical fallbacks in the summarization system, the bot achieves a target uptime and cost-efficiency while providing developers with the necessary artifacts for debugging.