Enrichers¶

Add contextual data to your events using CSV lookup tables.

What are Enrichers?¶

Enrichers are CSV-based lookup tables that can be used during data transformation to add additional fields to your events. For example, you can:

Add user information based on user IDs
Map IP addresses to geographic locations or internal network zones
Translate error codes to human-readable descriptions
Add department or cost center information based on employee IDs

Creating an Enricher¶

Step 1: Prepare Your CSV File¶

Your CSV file must have:

A header row with column names (first row)
One column designated as the index/lookup column
Additional columns with the data you want to add to events

Example CSV:

user_id,department,manager,location
U001,Engineering,Jane Smith,Building A
U002,Sales,John Doe,Building B
U003,Marketing,Alice Johnson,Building A

Step 2: Create the Enricher¶

Navigate to Enrichers in the dashboard
Click Create Enricher
Enter a name (alphanumeric characters only)
Optionally add a description
Upload your CSV file
Select the index column (the column used for lookups)
Click Save

Using Enrichers in Transformations¶

Once created, enrichers can be used in your transformation pipelines with the enricher filter:

{
  "type": "enricher",
  "config": {
    "enricher_id": "your-enricher-uuid",
    "source_field": "user_id",
    "target_field": "user_info"
  }
}

Configuration Options¶

Option	Required	Description
`enricher_id`	✓	The UUID of the enricher to use
`source_field`	✓	The field in your event to match against the enricher's index column
`target_field`		Where to store the enriched data. Defaults to `src.{source_field}-{enricher_name}`

Note

When no match is found in the enricher table, the target field will not be added to the event.

Updating Enricher Data¶

You can update the data in an existing enricher by uploading a new CSV file. The new file must have the same columns as the original. The index column cannot be changed after creation.

Best Practices¶

Practice	Description
Focused tables	Keep enricher tables focused—one table per type of lookup
Meaningful names	Use meaningful column names that will make sense in your enriched events
Unique index values	Index columns should contain unique values for best performance
Data freshness	Consider data freshness—update enricher data as your source data changes

Example: User Enrichment¶

1. Create a CSV file (users.csv):

employee_id,full_name,department,office
E001,Alice Johnson,Engineering,NYC
E002,Bob Smith,Marketing,LAX
E003,Carol Williams,Sales,CHI

2. Create the enricher: - Name: user-lookup - Index column: employee_id

3. Use in transformation:

{
  "type": "enricher",
  "config": {
    "enricher_id": "abc123-uuid",
    "source_field": "emp_id",
    "target_field": "employee"
  }
}

4. Result:

Input event:

{"timestamp": "2024-01-15T10:00:00Z", "emp_id": "E001", "action": "login"}

Output event:

{
  "timestamp": "2024-01-15T10:00:00Z",
  "emp_id": "E001",
  "action": "login",
  "employee": {
    "employee_id": "E001",
    "full_name": "Alice Johnson",
    "department": "Engineering",
    "office": "NYC"
  }
}