How to Configure Rate Limiting for Alerts in Multi-Cam Face Tracker

Set the rate_limit value in config/config.yaml under the telegram section to define the minimum seconds between consecutive Telegram alerts.

The Multi-Cam Face Tracker repository provides a built-in rate-limiting mechanism to prevent Telegram notification spam when multiple cameras detect faces in quick succession. By configuring this setting, you control how frequently the system pushes alerts to your chat, ensuring important detection events are reported without flooding the channel.

Understanding the Rate-Limiting Architecture

The rate-limiting system operates through three coordinated components that enforce a minimum time interval between alert transmissions.

Configuration Layer

The interval threshold is defined in config/config.yaml within the telegram mapping. The rate_limit key accepts an integer representing seconds:

telegram:
  enabled: true
  bot_token: "YOUR_BOT_TOKEN"
  chat_id: "YOUR_CHAT_ID"
  rate_limit: 30  # Minimum seconds between alerts

The default configuration sets this value to 30 seconds, which means the system will suppress any alert attempts that occur within 30 seconds of the previous successful transmission.

Alert System Initialization

When the application launches, core/alert_system.py instantiates the TelegramManager class and passes the configured rate limit as a constructor argument:

# core/alert_system.py

if config.get('telegram', {}).get('enabled', False):
    self.telegram = TelegramManager(
        config['telegram']['bot_token'],
        config['telegram']['chat_id'],
        config['telegram']['rate_limit']  # Passed as min_interval

    )

This initialization ensures the rate-limiting threshold is established before any detection events occur.

Enforcement Mechanism

The actual throttling logic resides in core/telegram_manager.py within the send_alert method. This function compares the current timestamp against self.last_sent (the timestamp of the previous alert) and aborts the operation if the elapsed time is less than self.min_interval:

# core/telegram_manager.py

def send_alert(self, message, image=None):
    now = time.time()
    if now - self.last_sent < self.min_interval:
        logging.warning(f"Telegram rate limit reached ({self.min_interval}s)")
        return
    
    # Proceed with sending alert...

    self.last_sent = now

If the rate limit is active, the method logs a warning and returns early without transmitting the message.

Step-by-Step Configuration Guide

Follow these steps to customize the alert frequency for your deployment:

1. Locate the configuration file at config/config.yaml in your repository root.

2. Edit the rate limit value under the telegram section. For example, to allow alerts every 10 seconds instead of 30:

   telegram:
     enabled: true
     bot_token: "YOUR_BOT_TOKEN"
     chat_id: "YOUR_CHAT_ID"
     rate_limit: 10

3. Save the file and restart the application. The Multi-Cam Face Tracker reads configuration values at launch time, so changes require a restart to take effect.

4. Verify the configuration by checking the application logs. When the first alert triggers after restart, you should see initialization messages confirming the TelegramManager received the correct interval value.

Advanced Runtime Customization

While the YAML configuration sets the baseline rate limit, you can modify the threshold programmatically during runtime for dynamic scenarios. Access the min_interval attribute directly on the TelegramManager instance:

# Example: Increase rate limit after detecting suspicious activity

alert_system.telegram.min_interval = 60  # Increase to 60 seconds

This approach is useful when implementing adaptive throttling based on detection frequency or time-of-day patterns. However, note that these runtime changes are not persisted to the configuration file and will reset to the YAML value on application restart.

Summary

• Configuration location: Set rate_limit in config/config.yaml under the telegram section to control seconds between alerts.
• Default behavior: The system enforces a 30-second minimum interval between Telegram notifications to prevent spam.
• Implementation files: core/alert_system.py initializes the limit, while core/telegram_manager.py enforces it via timestamp comparison in send_alert.
• Deployment workflow: Edit the YAML value and restart the application to apply changes, or modify telegram.min_interval at runtime for temporary adjustments.

Frequently Asked Questions

What happens if I set the rate limit to 0?

Setting rate_limit: 0 in config/config.yaml effectively disables throttling. The send_alert method in core/telegram_manager.py will evaluate now - self.last_sent < 0 as false (assuming positive timestamps), allowing every alert to transmit immediately regardless of timing.

Can different cameras have different rate limits?

The current implementation in aarambhdevhub/multi-cam-face-tracker uses a single global TelegramManager instance shared across all camera streams. The rate limit applies to the entire alert system rather than per-camera. To implement camera-specific throttling, you would need to modify core/alert_system.py to maintain separate last_sent timestamps for each camera ID.

Why are my configuration changes not taking effect?

The Multi-Cam Face Tracker reads config/config.yaml only during initialization. If you modify the rate_limit value while the application is running, the changes will not apply until you restart the service. Additionally, verify that you are editing the correct file path and that the YAML indentation matches the expected structure (two spaces per level).

How can I monitor when rate limiting is active?

The system logs throttling events at the WARNING level. When send_alert in core/telegram_manager.py suppresses a message due to rate limiting, it emits: logging.warning(f"Telegram rate limit reached ({self.min_interval}s)"). Configure your logging handler to capture WARNING level messages from the core.telegram_manager module to monitor suppression events in real-time.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}