Behaviors

Behaviors allow us to move beyond simple event-based tracking, which is a point-in-time insight (e.g. the user's current location) to more valuable and complex insights based on previous events.

Usually, converting event data into behavioral data requires complicated streaming infrastructure, like Flink, Kafka Streams, etc. However, Honeypot allows us to define custom aggregations and behaviors using a simple configuration syntax.

Not only do we remove the need for dedicated infrastructure for enriching / aggregating data, but we also derive insights much earlier: as soon as the events are generated. This is sometimes called a "shift left" approach.

Configuration Structure

Alternative Approach

Don't like writing JSON? Or want a simpler approach? You can specify the behavior you want to track in plain English using the Honeypot UI, which will generate the configuration for you.

Each behavior is configured using a JSON configuration syntax:

{
  "name": "behavior_name",
  "description": "Human-readable description",
  "group_by": "field_to_group_by",
  "operation": "operation_type",
  "fields": ["field1", "field2"],
  "window_duration_seconds": 3600,
  "filters": {
    "field": "event_name",
    "operator": "equals",
    "value": "login"
  },
  "operation_config": {...}
}

Core Configuration Properties

Required Properties

Property	Type	Description
name	string	Feature name used for referencing results. For example, if you name the feature login_count_10m, then Honeypot will return the computed feature data under the same key name in the behaviors object. See the response schema here.
group_by	object	Defines data source and grouping strategy. Can be any valid identifier or customer event property. Common values include: device_id - Group by device identifier identity - Group by user identity/email session_id - Group by session ip_address - Group by IP address event_properties.phone - Group by phone number (nested field) event_properties.email - Group by email from event properties See valid identifiers for more information.
operation	string	Type of aggregation to perform. Common values include: count - Count events within time window unique - Track unique values for fields distance - Calculate geographic distance between events proximity - Track proximity to normal location ratio - Calculate ratios between event types sequence - Detect ordered event sequences time_between - Measure time between events See operation details for configuration and examples.
window_duration_seconds	number	Time window for data retention (in seconds). Common values include: 60 - 1 minute 300 - 5 minutes 900 - 15 minutes 3600 - 1 hour 86400 - 24 hours 604800 - 7 days 2592000 - 30 days 31536000 - 365 days See time windows for more information.

Optional Properties

Property	Type	Description
description	string	Human-readable description of the feature
fields	string[]	Fields required for the operation
filters	object	Rules to filter which events are processed. See filters for more information.
operation_config	object	Operation-specific configuration options
timestamp_field	string	Custom timestamp field (defaults to event_time)

Supported Group By Fields

• device_id - Group by device identifier
• identity - Group by user identity/email
• session_id - Group by session
• ip_address - Group by IP address
• event_properties.phone - Group by phone number (nested field)
• event_properties.email - Group by email from event properties

Note: Use dot notation for nested fields.