Lookup Fields
Enriches telemetry by matching the value of a field against an external lookup source. For each record, the processor reads the chosen field, looks it up in a CSV file or a Redis server, and on a match adds the other fields from the matching record to the same context (Attributes, Body, or Resource).
Supported Telemetry Types
✓
✓
✓
Select one or more signals; the same lookup configuration enriches every selected signal.
Configuration
Basic Configuration
Selection
Choose Telemetry Type
Telemetry Selector
Yes
Logs
The signals this instance runs on. Select Logs, Metrics, and/or Traces.
Context
Enum: Attributes, Body, Resource
No
Attributes
Where the source field is read from, and where matching fields are added.
Field
OTTL Field
Yes
—
The field to look up in the selected context. A lookup runs when this field's name and value match a record in the source. Enter the field name (e.g. host.name or ip), not a full OTTL path.
Lookup
Source Type
Enum: CSV, Redis
Yes
CSV
The data source used for lookups. Choose CSV to match against a file, or Redis to query a Redis server.
CSV File Path
String
Yes *
—
Path to the CSV file containing lookup values. The file must be accessible on the collector host and include the .csv extension. Applies when Source Type is CSV.
* CSV File Path is required when Source Type is CSV.
Redis
These parameters apply when Source Type is Redis.
Redis Host
String
Yes
localhost
Hostname or IP address of the Redis server.
Redis Port
Integer
Yes
6379
TCP port of the Redis server (1–65535).
Redis Username
String
No
(empty)
Username for Redis authentication.
Redis Password
String
No
(empty)
Password for Redis authentication. Stored as a sensitive value.
Redis Database
Integer
No
0
The Redis database number.
Key Prefix
String
No
(empty)
Prefix prepended to lookup keys, joined with a colon (:).
Advanced
These parameters apply when Source Type is Redis.
Enable TLS
Boolean
No
false
Enable TLS for Redis connections.
Enable Cache
Boolean
No
true
Cache lookup results locally to reduce external Redis calls. The cache is per-collector and resets on restart.
Redis Dial Timeout
String
No
(empty)
Bounds the initial TCP/TLS dial to Redis (e.g. 2s, 500ms). Empty uses the processor default.
Cache TTL
String
No
5m
How long cached entries remain valid (e.g. 5m, 1h). Applies when Enable Cache is on.
Redis Lookup Timeout
String
No
(empty)
Bounds each Redis lookup call (e.g. 5s, 1s). Empty uses the processor default.
Examples
Enrich metrics from a CSV by host name
This instance looks up the host.name resource value of incoming metrics against a CSV file. When a row's host.name matches, the other columns from that row (here region and env) are added to the same context. For example, a metric with host.name of MacBook-Pro-4.local gains region=us-east and env=prod.
Example CSV:
Look up from Redis with caching and bounded timeouts
This instance sets Source Type to Redis and looks up the host.name attribute for incoming logs. With Key Prefix lookup, a log whose host.name is web-01 reads the Redis key lookup:web-01, and the returned fields (such as region and env) are added to the log attributes. The advanced parameters are exercised here: Enable Cache is on with a Cache TTL of 10m, a Redis Dial Timeout of 2s, and a Redis Lookup Timeout of 5s to bound the connection and per-lookup calls.
The processor first tries HGETALL against the key. If that returns nothing, it falls back to GET and parses the value as a JSON object of strings. Store lookup data as either a Redis hash or a JSON string:
Configuration Tips
Enter Field as a plain field name (e.g.
host.name), not an OTTL path expression. The processor reads and writes it within the selected Context.When using a CSV source, the processor reloads the file periodically, so you can update lookup data without restarting the collector.
For Redis, set Key Prefix to namespace your lookup keys; it is joined to the field value with a colon.
Troubleshooting
Fields are not added after a lookup
Symptoms: matching records exist in the source, but no new fields appear on the telemetry.
Solutions:
Confirm the Context is the one that actually holds the source field, and that Field is a plain name (not an OTTL path).
For CSV, verify the file path is correct and readable on the collector host and that a header matches the Field name. For Redis, confirm the key (Key Prefix plus the field value) exists.
Lookup results don't show in Live Preview
Symptoms: enrichment isn't visible when previewing the configuration.
Solutions: Lookup results depend on an external file or server and won't appear in Live Preview. Roll out the configuration, then use "View Recent Telemetry" on the agent page or inspect a downstream processor node to verify.
The collector fails to start with a Redis source
Symptoms: the collector exits at startup instead of failing on the first lookup.
Solutions: On startup the processor sends a PING to Redis within the dial timeout. Confirm Redis Host, Redis Port, and credentials are correct and the server is reachable. Adjust Redis Dial Timeout if the network is slow.
Standalone Processor
Related Resources
Bindplane Resources
These processors enrich and reshape telemetry alongside Lookup Fields. Chain them to parse, normalize, and add context to your data:
Last updated
Was this helpful?