# Lookup Fields

### Description

The Lookup Fields processor can be used to add matching telemetry fields from a CSV file.

### Use

The Lookup Fields processor is used to dynamically add fields based on an existing telemetry value. For each unit of telemetry processed, this processor will grab the value of a field and perform a lookup using a CSV file. If that value exists, the processor will add all other fields associated with that CSV row.

The processor re-reads the CSV file every 60 seconds, allowing updates to be made without restarting the collector.

### Supported Types

| Metrics | Logs | Traces | Bindplane Collector |
| ------- | ---- | ------ | ------------------- |
| ✓       | ✓    | ✓      | `v1.45.0\`+         |

### Configuration

<table><thead><tr><th width="97.19140625">Field</th><th>Description</th></tr></thead><tbody><tr><td>CSV</td><td>The CSV file used to perform a lookup operation. The file path should include the <code>.csv</code> extension, and the file must be accessible on the collector host at the specified path.</td></tr><tr><td>Context</td><td>The 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.</td></tr><tr><td>Field</td><td>The 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., <code>host.name</code> or <code>ip</code>), not an OTTL path expression (e.g., <code>resource["host.name"]</code> or <code>body["ip"]</code>).</td></tr></tbody></table>

{% 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 %}

### 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**

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2Fgit-blob-afd8e98dafaa9ab08af771f7ab0a29a6eaf3cb48%2Fintegrations-processors-lookup-fields-image-1.png?alt=media" alt="Bindplane docs - Lookup Fields - image 1"><figcaption></figcaption></figure>

**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**

<figure><img src="https://1405008107-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmiOMzBfoNFwmKJFHMcJ%2Fuploads%2FFwaZ6N4EQDr4VtmQ09sF%2FXnapper-2026-02-06-11.48.50.png?alt=media&#x26;token=2ced6ddc-d5cd-47fd-94b0-7779fadadec7" alt="Bindplane docs - Lookup Fields - image 1"><figcaption></figcaption></figure>

**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
```