Skip to main content
Detection aggregation groups similar findings together within a time window, reducing alert noise while preserving all detection data for analysis.

​
How It Works

Blocklight uses an adaptive sliding window approach that balances low latency with effective noise reduction. Aggregated findings are emitted as soon as they’re ready, not at fixed intervals.

​
Smart Emission Strategy

Aggregated findings are emitted when:
  1. Window elapsed + min_count reached - The configured time window has passed AND minimum detections are met
  2. Burst detection - 3x the min_count is reached (immediate emission, even if window hasn’t elapsed)
  3. Continuous monitoring - System checks every 1-5 seconds for ready aggregations
This means:
  • ✅ Low latency: Findings are emitted as soon as they’re ready
  • ✅ Adaptive: Burst attacks trigger immediate alerts
  • ✅ Efficient: Reduces noise without sacrificing responsiveness

​
Aggregation Criteria

Detections are grouped when they share:
  • Same rule name - Must match the same detection rule
  • Same chain - Must be on the same blockchain network
  • Same block number - Must occur in the same block
  • Within time window - Must occur within window_seconds (default: 15 seconds)

​
Example: Without Aggregation

Without aggregation, a single attack pattern can generate many alerts: 
🚨 Large transfer detected (tx=0xabc...)
🚨 Large transfer detected (tx=0xdef...)
🚨 Large transfer detected (tx=0x123...)
🚨 Large transfer detected (tx=0x456...)
... more alerts ...
This creates alert fatigue and makes it difficult to identify the attack pattern.

​
Example: With Aggregation

With aggregation enabled, similar detections are grouped into a single alert: 
🚨 Large transfer detected (100 occurrences)
   - Time window: 15 seconds
   - Block: 18,500,000
   - Chain: ethereum
   - First detection: 2024-01-15 10:23:45
   - Last detection: 2024-01-15 10:24:00
This provides a clear overview while preserving access to individual detections.

​
Configuration

Configure aggregation in config.yaml: 
aggregation:
  enabled: true
  window_seconds: 15        # Time window to accumulate detections (min: 5, max: 3600)
  min_count: 2              # Minimum detections needed to aggregate (min: 1, max: 100)
  preserve_individual: true # Keep individual detections accessible

​
Configuration Options

  • enabled - Enable or disable aggregation globally
  • window_seconds - Time window for grouping detections (default: 15 seconds)
    • Findings are grouped if they arrive within this window from the first detection
    • Aggregations are emitted as soon as the window elapses
    • If 3x min_count is reached, emission happens immediately regardless of window
    • Increase for higher noise reduction (e.g., 30-60 seconds)
    • Decrease for more granular alerts (e.g., 5-10 seconds)
  • min_count - Minimum number of detections required to create an aggregation (default: 2)
    • Set to 3-5 for very noisy environments
    • Set to 2 for balanced noise reduction
    • Note: Findings below min_count are emitted individually if preserve_individual: true
  • preserve_individual - Whether to keep individual detections accessible (default: true)
    • Set to true for forensics and detailed analysis
    • Set to false to save memory (individual detections are discarded)
    • Important: When true, findings below min_count are still emitted as individual alerts

​
Use Cases

​
High-Volume Monitoring

When monitoring high-traffic protocols or popular tokens, aggregation prevents alert storms: 
aggregation:
  enabled: true
  window_seconds: 30        # Longer window for high-volume scenarios
  min_count: 5              # Require more detections before aggregating
  preserve_individual: true

​
Multiple Transfers Detection

Transactions with many token transfers can generate multiple detections. Aggregation groups them: 
aggregation:
  enabled: true
  window_seconds: 5         # Short window for transaction-level grouping
  min_count: 2
  preserve_individual: true # Important for forensics

​
Token Transfer Monitoring

When monitoring token transfers, aggregation reduces noise from legitimate high-volume activity: 
aggregation:
  enabled: true
  window_seconds: 60        # Longer window for transfer monitoring
  min_count: 10             # Only aggregate significant volumes
  preserve_individual: true

​
Best Practices

  1. Start with defaults - The default configuration works well for most scenarios
  2. Tune based on volume - Increase window_seconds and min_count for high-volume environments
  3. Preserve individual detections - Keep preserve_individual: true for forensics unless memory is constrained
  4. Monitor aggregation stats - Use the API to monitor aggregation effectiveness
  5. Test with dry-run - Use blocklight dry-run to test aggregation behavior before production

​
Accessing Aggregated Data

Aggregated findings are available through the REST API. Individual detections remain accessible when preserve_individual: true. See API Reference for endpoint details.