> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/processors/lookup-fields.md). # Lookup Fields ### Description The Lookup Fields processor can be used to add matching telemetry fields from a CSV file or a Redis server. ### Use The Lookup Fields processor adds fields by matching an existing telemetry value against an external source. For each telemetry item, the processor reads the selected field and performs a lookup. If it finds a match, it adds the other fields from the matching record to the same context. When using a CSV file, the processor reloads the file every 60 seconds. This lets you update lookup data without restarting the collector. You can also use Redis as the lookup source. Set **Source Type** to `Redis` to configure the connection. Redis is queried for each lookup, and the default in-memory cache reduces repeated calls. ### Supported Types | Metrics | Logs | Traces | Bindplane Collector | | ------- | ---- | ------ | ------------------- | | ✓ | ✓ | ✓ | `v1.45.0+` | {% hint style="info" %} The Redis data source requires collector version `v1.100.0` or later. {% endhint %} ### Configuration
FieldDescription
Source TypeThe data source used to perform lookups. Choose CSV to look up values in a CSV file, or Redis to look up values in a Redis server. Defaults to CSV.
CSVThe CSV file used to perform a lookup operation. The file path should include the .csv extension, and the file must be accessible on the collector host at the specified path.
ContextThe context of the lookup operation. The source field must exist here in order to perform a lookup. If a lookup succeeds, all matching fields are also added to this location.
FieldThe field to lookup in the specified context. A lookup operation is performed if the name and value of this field match a header and value in the CSV file. Enter only the field name (e.g., host.name or ip), not an OTTL path expression (e.g., resource["host.name"] or body["ip"]).
{% hint style="warning" %} Lookup results will not appear in [Live Preview](https://docs.bindplane.com/feature-guides/live-preview). To verify the results, roll out the configuration and click the "View Recent Telemetry" button on the agent page, or inspect a downstream processor node. This limitation applies to all processors and connectors that depend on external files or resources. {% endhint %} #### Redis This section appears when **Source Type** is `Redis`. The processor connects to Redis and looks up the value of **Field** for each telemetry item. | Field | Default | Description | | -------------- | ----------- | ----------------------------------------------------------------- | | Redis Host | `localhost` | Hostname or IP address of the Redis server. | | Redis Port | `6379` | TCP port of the Redis server. | | Redis Username | | Username for Redis authentication. Optional. | | Redis Password | | Password for Redis authentication. Optional. | | Redis Database | `0` | Redis database number. | | Key Prefix | | Prefix added to lookup keys, joined with a colon (`:`). Optional. | **Advanced settings** | Field | Default | Description | | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Enable TLS | `false` | Enable TLS 1.2 or later for Redis connections. | | Enable Cache | `true` | Cache lookup results in memory to reduce Redis calls. The cache is local to each collector and resets when the collector restarts. | | Cache TTL | `5m` | How long cached entries remain valid. Examples: `5m`, `1h`. Shown when **Enable Cache** is on. | | Redis Dial Timeout | `2s` | Timeout for the initial Redis connection. Examples: `2s`, `500ms`. Leave empty to use the default. | | Redis Lookup Timeout | `5s` | Timeout for each Redis lookup. Examples: `5s`, `1s`. Leave empty to use the default. | **How Redis lookups work** The lookup key is the value of **Field**. If **Key Prefix** is set, the processor prepends it and joins it with a colon. For example, if **Key Prefix** is `lookup` and `host.name` is `web-01`, the processor reads the key `lookup:web-01`. 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. Each returned key-value pair is added to the configured **Context**. Store lookup data as either a Redis hash or a JSON string: ``` # Redis hash HSET lookup:web-01 region us-east env prod # JSON string SET lookup:web-01 '{"region":"us-east","env":"prod"}' ``` On startup, the processor sends a `PING` to Redis within the configured dial timeout. If Redis is unreachable or authentication fails, the collector fails to start instead of failing later on the first lookup. ### Example Configurations #### Adding Fields Based on Host In this configuration, the processor will perform a lookup on the `host.name` value of all incoming metrics. If this field exists on the resource of a metric and the specified CSV file contains a matching value with that header, all other fields in that CSV row will be added to the metric. For example, in this particular configuration, if a metric has a value of `MacBook-Pro-4.local` for `host.name`, the corresponding values for `region` and `env` will automatically be added to the same context. **Web Interface**
Bindplane docs - Lookup Fields - image 1
**Example CSV** ```csv host.name,region,env MacBook-Pro-4.local,us-east,prod MacBook-Pro-3.local,us-west,dev MacBook-Pro-2.local,us-central,dev MacBook-Pro-1.local,us-central,prod ``` #### Enriching Logs Based on IP In this configuration, the processor performs a lookup on the `ip` field in the log body. If a log has a body field named `ip` whose value matches a row in the CSV, all other columns from that row are added to the log body. **Web Interface**
Bindplane docs - Lookup Fields - image 1
**Example CSV** ```csv ip,region,risk_level 10.0.0.1,us-east,low 192.168.1.50,us-west,high 172.16.0.10,ap-south,medium ``` #### Enriching Logs via Redis In this configuration, the processor looks up the `host.name` attribute for incoming logs in Redis. If a log has `host.name` set to `web-01` and **Key Prefix** is `lookup`, the processor reads the key `lookup:web-01`. It then adds the returned fields, such as `region` and `env`, to the log attributes. **Web Interface**
**Example Redis data** ``` HSET lookup:web-01 region us-east env prod HSET lookup:web-02 region us-west env dev ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/integrations/processors/lookup-fields.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.