Televerse Documentation

The Logging Plugin is a powerful built-in tool that provides detailed insights into your bot's interactions with the Telegram API. It's an essential utility for development, debugging, and production monitoring.

This plugin automatically logs requests sent to the Telegram Bot API and their responses, giving you visibility into network traffic, payload structures, and execution times.

Installation

The Logging Plugin is part of the core Televerse package, so you don't need to install any external dependencies. Simply import it from televerse/plugins/logging.dart.

Basic Usage

To start using the logger, simply attach it to your bot instance using the plugin method.

main.dart

import 'package:televerse/televerse.dart';
import 'package:televerse/plugins/logging.dart';

void main() {
  final bot = Bot("YOUR_BOT_TOKEN");
  
  // Attach the logging plugin
  bot.plugin(LoggingPlugin());
  
  bot.start();
}

By default, this will enable comprehensive logging with colored output, pretty-printed JSON, and detailed request/response information.

Configuration

The LoggingPlugin is highly configurable through the options parameter, which accepts aLoggerOptions object. You can fine-tune what exactly gets logged.

Pre-defined Configurations

Televerse provides several named constructors for common use cases:

main.dart

// Default configuration (detailed, colored)
bot.plugin(LoggingPlugin());

// Detailed configuration (explicit)
bot.plugin(LoggingPlugin(
  options: LoggerOptions.detailed(),
));

// Minimal configuration (request/method names only, no bodies)
bot.plugin(LoggingPlugin(
  options: LoggerOptions.minimal(),
));

// Errors only (quiet during normal operation)
bot.plugin(LoggingPlugin(
  options: LoggerOptions.errorsOnly(),
));

// Production safe (no colors, sensitive data might still need care but less noise)
bot.plugin(LoggingPlugin(
  options: LoggerOptions.production(),
));

Custom Configuration

You can customize every aspect of the logger by creating a custom LoggerOptions instance:

main.dart

bot.plugin(LoggingPlugin(
  options: LoggerOptions(
    // Enable/disable specific log components
    request: true,        // Log request method and ID
    requestBody: true,    // Log parameters and files
    responseBody: true,   // Log the API response
    error: true,          // Log error messages
    stackTrace: true,     // Log stack traces on error
    
    // Formatting options
    prettyPrint: true,    // Indent JSON for readability
    colorOutput: true,    // Use ANSI colors in terminal
    
    // Filter specific methods
    methods: [
      APIMethod.sendMessage, 
      APIMethod.sendPhoto,
    ],
  ),
));

Output Example

When enabled, the logger produces structured, readable output in your console:

📤 [10:23:45.123] sendMessage [K7L2M9]

┌─ Request Body:

│ Parameters:

│ chat_id: 123456789

│ text: "Hello, World!"

✅ sendMessage [K7L2M9] completed in 145ms

┌─ Response Body:

│ {

│ "ok": true,

│ "result": { ... }

│ }

Saving Logs to File

By default, the logger prints to the standard output (console). You can redirect logs to a file or any other destination by providing a custom logPrint function.

main.dart

import 'dart:io';

void main() {
  final bot = Bot("TOKEN");
  final logFile = File('bot.log');
  
  bot.plugin(LoggingPlugin(
    options: LoggerOptions(
      // Custom printer function
      logPrint: (message) {
        // Append to file instead of printing to console
        logFile.writeAsStringSync(
          '$message\n', 
          mode: FileMode.append,
        );
      },
    ),
  ));
  
  bot.start();
}