Notification Throttling

Notification throttling allows you to control the rate at which notifications are sent, preventing notification spam and managing costs for paid notification channels like SMS.

Overview

LIVCK includes a powerful notification throttling system that limits how many notifications can be sent within a specific time window. This is particularly important for:

  • Cost Control - Prevent excessive SMS charges
  • Spam Prevention - Avoid overwhelming team members with too many notifications
  • Rate Limiting - Comply with provider rate limits
  • Resource Management - Reduce server load during high-alert periods

How It Works

The throttling system tracks the number of notifications sent and applies limits based on your configuration. When the limit is reached, additional notifications are queued or dropped until the time window resets.

Key Components

Notification Limits:

  • Enable or disable the entire throttling system
  • When disabled, all notifications are sent immediately without limits

Limit Scope:

  • Global Limit - Apply the same limit across all users system-wide
  • User Limit - Apply limits per individual user

SMS Decay (seconds):

  • The time window for counting notifications
  • Default: 3600 seconds (1 hour)
  • Notifications older than this window are not counted toward the limit

SMS Limit:

  • Maximum number of SMS notifications allowed within the decay window
  • Default: 10 notifications per hour
  • Applies to the scope (global or per-user)

Configuration

Notification throttling is configured in the LIVCK admin panel under Settings.

Step 1: Access Throttling Settings

  1. Log in to LIVCK admin panel
  2. Navigate to Settings
  3. Find the Notification Limits section

Step 2: Configure Throttling

Enable/Disable Notification Limits:

  • Toggle the Notification Limits checkbox
  • ✅ Enabled: Throttling is active
  • ❌ Disabled: All notifications sent immediately (no limits)

Choose Limit Scope:

  • Global Limit: One shared limit for all users combined
  • User Limit: Each user has their own independent limit

Set SMS Decay (seconds):

  • Enter the time window in seconds
  • Common values:
    • 3600 = 1 hour
    • 7200 = 2 hours
    • 86400 = 24 hours

Set SMS Limit:

  • Enter the maximum number of SMS notifications allowed within the decay window
  • Consider your budget and team size when setting this value

Step 3: Save Configuration

Click Save to apply the throttling settings.

Configuration Examples

Example 1: Conservative Global Limit

Prevent system-wide SMS spam with a strict global limit:

Notification Limits: ✅ Enabled
Limit Scope: Global Limit
SMS Decay: 3600 (1 hour)
SMS Limit: 10

Result: Maximum of 10 SMS messages sent system-wide per hour, regardless of how many users are configured to receive SMS.

Example 2: Per-User Limit

Allow each user to receive their own set of notifications:

Notification Limits: ✅ Enabled
Limit Scope: User Limit
SMS Decay: 3600 (1 hour)
SMS Limit: 5

Result: Each user can receive up to 5 SMS messages per hour. With 10 users, up to 50 SMS could be sent per hour total.

Example 3: Daily Limit

Set a daily SMS budget:

Notification Limits: ✅ Enabled
Limit Scope: Global Limit
SMS Decay: 86400 (24 hours)
SMS Limit: 50

Result: Maximum of 50 SMS messages sent per day across all users.

Example 4: No Throttling

Disable all limits for critical systems:

Notification Limits: ❌ Disabled

Result: All notifications sent immediately without any throttling. Use with caution as this can lead to high costs.

Understanding Limit Scopes

Global Limit

All SMS notifications are counted together in a single shared pool.

Use Cases:

  • Strict cost control
  • Small budgets
  • Preventing system-wide spam
  • Shared ClickSend account with limited credits

Example:

  • Limit: 10 SMS per hour (global)
  • User A triggers 6 alerts
  • User B triggers 5 alerts
  • Result: User A receives 6 SMS, User B receives only 4 SMS (global limit of 10 reached)

User Limit

Each user has their own independent notification count.

Use Cases:

  • Fair distribution of notifications
  • Larger teams
  • Per-user cost allocation
  • Ensuring critical users always receive notifications

Example:

  • Limit: 5 SMS per hour (per user)
  • User A triggers 10 alerts
  • User B triggers 3 alerts
  • Result: User A receives 5 SMS (user limit), User B receives 3 SMS

How Throttling Affects Notifications

When Limit is Reached

Once the limit is reached:

  1. Additional SMS notifications are not sent
  2. Other notification channels (email, Slack, Telegram, Pushover) continue to work normally
  3. The limit resets after the decay window expires
  4. Notifications that were blocked are not queued or retried

Which Notifications are Affected

Affected:

  • SMS notifications only

Not Affected:

  • Email notifications
  • Slack notifications
  • Telegram notifications
  • Pushover notifications

Throttling only applies to SMS to control costs. All other notification channels remain unaffected.

Best Practices

Cost Control

Calculate Your Budget:

  1. Determine monthly SMS budget (e.g., €50/month)
  2. Divide by average SMS cost (e.g., €0.08/SMS) = 625 SMS/month
  3. Divide by 30 days = ~20 SMS/day
  4. Set daily limit: SMS Decay = 86400, SMS Limit = 20

Monitor Usage:

  • Check ClickSend dashboard regularly
  • Review SMS delivery logs
  • Adjust limits based on actual usage
  • Set up low balance alerts in ClickSend

Notification Strategy

Prioritize Critical Alerts:

  • Use SMS only for critical incidents
  • Use email/Slack/Telegram for routine updates
  • Reserve SMS for high-priority status changes
  • Consider implementing alert severity levels

Combine Multiple Channels:

  • Don't rely solely on SMS
  • Configure email + Slack + SMS for redundancy
  • Email for detailed information
  • SMS for immediate critical alerts
  • Slack for team coordination

Team Size Considerations

Small Teams (1-5 users):

  • Use per-user limits for fair distribution
  • Higher per-user limit (e.g., 10 SMS/hour)
  • More predictable costs

Large Teams (10+ users):

  • Use global limits for strict cost control
  • Lower per-user limit if using user limits
  • Consider staggered notification distribution

Time Window Selection

Short Windows (1 hour):

  • Better burst protection
  • Smoother cost distribution
  • Prevents rapid alert spam

Long Windows (24 hours):

  • Daily budget control
  • May allow bursts within the day
  • Easier to predict monthly costs

Monitoring and Troubleshooting

Checking if Throttling is Active

Signs of Active Throttling:

  • SMS notifications stop arriving after reaching limit
  • Other channels (email, Slack) still working
  • Notifications resume after decay window expires

Check Logs:

docker compose logs app | grep -i throttle
docker compose logs app | grep -i "sms limit"

SMS Not Sending

Possible Causes:

  1. Throttling limit reached - Wait for decay window to reset
  2. Notification limits disabled - Check if limits are enabled
  3. ClickSend issues - Check account balance and API credentials
  4. Phone number incorrect - Verify phone number format

Solution:

  • Check if limit was reached in the current window
  • Review throttling configuration
  • Check application logs
  • Verify ClickSend account status

Adjusting Limits During Incidents

If you need to temporarily increase limits during a critical incident:

  1. Navigate to Settings > Notification Limits
  2. Increase SMS Limit or SMS Decay window
  3. Save changes
  4. Changes apply immediately
  5. Remember to reset limits after the incident

Disabling Throttling Temporarily

For critical situations where all SMS must be sent:

  1. Navigate to Settings > Notification Limits
  2. Disable Notification Limits checkbox
  3. Save changes
  4. All SMS will be sent without limits
  5. Important: Re-enable throttling after the situation is resolved to prevent unexpected costs

Cost Examples

Scenario 1: No Throttling

Team: 10 users with SMS enabled
Incident: 20 updates over 2 hours
SMS per update per user: 1
Total SMS: 10 users × 20 updates = 200 SMS
Cost: 200 × €0.08 = €16.00 per incident

Scenario 2: Global Throttling

Team: 10 users with SMS enabled
Incident: 20 updates over 2 hours
Throttling: 10 SMS per hour (global)
Total SMS: 10 (hour 1) + 10 (hour 2) = 20 SMS total
Cost: 20 × €0.08 = €1.60 per incident
Savings: €14.40 per incident (90% reduction)

Scenario 3: User Throttling

Team: 10 users with SMS enabled
Incident: 20 updates over 2 hours
Throttling: 2 SMS per hour (per user)
Total SMS: 10 users × 2 (hour 1) + 10 users × 2 (hour 2) = 40 SMS total
Cost: 40 × €0.08 = €3.20 per incident
Savings: €12.80 per incident (80% reduction)

Advanced Configuration

Different Limits for Different Users

LIVCK currently doesn't support different limits per user. Workarounds:

Option 1: Role-Based Notification Strategy

  • Configure SMS only for critical team members (on-call engineers)
  • Other team members use email/Slack/Telegram

Option 2: Multiple LIVCK Instances

  • Separate LIVCK instances with different throttling configs
  • Each instance for different teams or priority levels

Integrating with Alert Severity

Consider implementing a notification strategy based on alert severity:

  • Critical: Always send SMS (ensure limits allow critical alerts)
  • High: Send SMS if within limits, otherwise email/Slack
  • Medium: Email and Slack only
  • Low: Email only

Security and Permissions

Who Can Configure Throttling

Only users with the setting.edit permission can configure notification throttling settings.

See Permissions for managing access control.

Audit Logging

Throttling configuration changes should be logged. Check application logs for throttling modifications:

docker compose logs app | grep -i "notification limit"

Additional Resources