Time Windows

The window_duration_seconds property defines how long data is retained and aggregated:

• Short windows (60-300s): Real-time fraud detection, rate limiting
• Medium windows (900-3600s): Session analysis, behavioral patterns
• Long windows (86400s+): User profiling, long-term trends

Common Values:

• 60 - 1 minute
• 300 - 5 minutes
• 900 - 15 minutes
• 3600 - 1 hour
• 86400 - 24 hours
• 604800 - 7 days
• 2592000 - 30 days
• 31536000 - 365 days

Complete Examples

Fraud Detection Setup

[
  {
    "id": "rapid_logins",
    "name": "rapid_login_attempts",
    "description": "Count login attempts in 5 minutes",
    "group_by": "device_id",
    "operation": "count",
    "window_duration_seconds": 300,
    "filters": { "field": "event_name", "operator": "equals", "value": "login" }
  },
  {
    "id": "failed_ratio",
    "name": "failed_login_ratio",
    "description": "Ratio of failed to total login attempts",
    "group_by": "device_id",
    "operation": "ratio",
    "fields": ["failed_login", "login"],
    "window_duration_seconds": 900,
    "filters": {
      "field": "event_name",
      "operator": "in",
      "value": ["login", "failed_login"]
    }
  },
  {
    "id": "location_jump",
    "name": "impossible_travel",
    "description": "Distance between consecutive logins",
    "group_by": "identity",
    "operation": "distance",
    "window_duration_seconds": 300,
    "filters": { "field": "event_name", "operator": "equals", "value": "login" }
  }
]

User Behavior Analysis

[
  {
    "id": "unique_devices",
    "name": "devices_per_user",
    "description": "Unique devices used by user in 30 days",
    "group_by": "device_id",
    "operation": "unique",
    "fields": ["device_id"],
    "window_duration_seconds": 2592000
  },
  {
    "id": "purchase_funnel",
    "name": "ecommerce_sequence",
    "description": "Track purchase funnel completion",
    "group_by": "session_id",
    "operation": "sequence",
    "fields": ["product_view", "add_to_cart", "checkout", "purchase"],
    "window_duration_seconds": 7200,
    "operation_config": {
      "allow_intermediate_events": true
    }
  }
]

Best Practices

1. Choose appropriate time windows: Balance between data freshness and computational efficiency
2. Use specific filters: Reduce unnecessary processing by filtering relevant events
3. Group by relevant identifiers: Choose grouping fields that align with your analysis goals
4. Monitor performance: Long windows and complex operations may impact performance
5. Test configurations: Use the test framework to validate behavior before deployment

Troubleshooting

Common Issues

1. Missing group_by values: Ensure the grouping field exists in your event data
2. Invalid timestamps: Check that event_time or custom timestamp fields are properly formatted
3. Filter mismatches: Verify filter conditions match your event structure
4. Memory usage: Very long windows or high-cardinality grouping can consume significant memory

Debugging Tips

• Check console logs for feature computation errors
• Verify cache keys are being generated correctly
• Test with small time windows first
• Use the aggregator test suite to validate configurations