> 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 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 | Logs | Metrics | Traces | | ---- | ------- | ------ | | ✓ | ✓ | ✓ | Select one or more signals; the same lookup configuration enriches every selected signal. ### Configuration #### Basic Configuration
Bindplane docs - Lookup Fields - image 1
**Selection** | Parameter | Type | Required | Default | Description | | --------------------- | -------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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** | Parameter | Type | Required | Default | Description | | ------------- | ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | Parameter | Type | Required | Default | Description | | -------------- | ------- | -------- | --------- | --------------------------------------------------------------- | | 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. | Parameter | Type | Required | Default | Description | | -------------------- | ------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------- | | 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: ```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 ``` #### Look up from Redis with caching and bounded timeouts
Bindplane docs - Lookup Fields - image 2
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: ``` # Redis hash HSET lookup:web-01 region us-east env prod # JSON string SET lookup:web-01 '{"region":"us-east","env":"prod"}' ``` ### 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: 1. Confirm the Context is the one that actually holds the source field, and that Field is a plain name (not an OTTL path). 2. 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 ```yaml apiVersion: bindplane.observiq.com/v1 kind: Processor metadata: name: lookup-fields spec: type: lookup_fields parameters: - name: telemetry value: - Logs - name: source_type value: Redis - name: context value: Attributes - name: field value: host.name - name: redis_host value: localhost - name: redis_port value: 6379 - name: redis_key_prefix value: lookup - name: cache_enabled value: true - name: cache_ttl value: 10m - name: redis_dial_timeout value: 2s - name: redis_lookup_timeout value: 5s ``` ### Related Resources * [Redis commands — HGETALL](https://redis.io/docs/latest/commands/hgetall/) * [Redis commands — GET](https://redis.io/docs/latest/commands/get/) ### Bindplane Resources These processors enrich and reshape telemetry alongside Lookup Fields. Chain them to parse, normalize, and add context to your data: * [Add Fields](/integrations/processors/add-fields.md) * [Parse JSON](/integrations/processors/parse-json.md) * [Parse CSV](/integrations/processors/parse-csv.md) * [Geo IP](/integrations/processors/geoip.md) --- # 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.