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


---

# Agent Instructions: 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:

```
GET https://docs.bindplane.com/integrations/processors/lookup-fields.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.