> 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/how-to-guides/collector-management/use-environment-variables-in-collector-configurations.md).

# Use Environment Variables in Collector Configurations

Environment variables let one Bindplane configuration carry values that differ from host to host, such as a datacenter name, a region, or a team. The collector reads each variable from its own environment when it loads the configuration, so the value never passes through Bindplane.

This guide covers setting variables for the collector service, referencing them in a configuration, and how they appear in processor previews. To keep credentials out of Bindplane with environment variables, see [Using Environment Variables](https://docs.bindplane.com/production-checklist/bindplane/secrets-management/using-environment-variables.md) in the secrets management docs.

### Set Environment Variables for the Collector

The collector runs as a system service, so it only sees variables set in the service's own environment. Variables exported in a shell session or added to a user's `.bashrc` don't reach it.

The collector reads its environment only when it starts. Restart it after adding or changing a variable.

{% tabs %}
{% tab title="Linux" %}
Create a systemd override for the collector service:

```bash
sudo systemctl edit observiq-otel-collector
```

Add one `Environment=` line per variable:

```ini
[Service]
Environment=DATACENTER=us-east-1
Environment=TEAM=payments
```

Save and close the editor, then restart the collector. `systemctl edit` reloads systemd when the editor closes, so no `daemon-reload` is needed.

```bash
sudo systemctl restart observiq-otel-collector
```

To keep a long list of variables out of the override, put them in a file with one `NAME=value` per line, and point the override at it with `EnvironmentFile=`:

```ini
[Service]
EnvironmentFile=/etc/default/observiq-otel-collector
```

To confirm the running collector has a variable, read its process environment:

```bash
sudo cat /proc/$(systemctl show -p MainPID --value observiq-otel-collector)/environ | tr '\0' '\n' | grep DATACENTER
```

{% endtab %}

{% tab title="Windows" %}
The collector service reads variables from the `Environment` value under its service registry key. From an elevated PowerShell prompt, set one `NAME=value` string per variable, then restart the service:

```powershell
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\observiq-otel-collector" `
  -Name Environment -Type MultiString -Value @("DATACENTER=us-east-1", "TEAM=payments")
Restart-Service observiq-otel-collector
```

{% hint style="warning" %}
This command replaces the service's whole `Environment` value. Include every variable the collector needs each time you run it.
{% endhint %}
{% endtab %}

{% tab title="AIX" %}
The collector's SRC subsystem gets its environment from `/etc/observiq-otel-collector.env`. It already sets the collector's home and storage directories, so add your variables to the end of its line:

```
BINDPLANE_COLLECTOR_HOME=/opt/observiq-otel-collector BINDPLANE_COLLECTOR_STORAGE=/opt/observiq-otel-collector/storage DATACENTER=us-east-1 TEAM=payments
```

SRC reads the file differently from a shell:

* **Everything stays on one line.** Separate the pairs with spaces. A tab doesn't separate them, so the pair after a tab becomes part of the value before it.
* **For a value with a space, quote the whole pair:** `"TEAM=payments east"`. SRC removes quotes only at the start of a pair. In `TEAM="payments east"`, or with single quotes or a backslash, the quotes or backslash become part of the value.
* **Don't put a lone `"` inside a value.** Everything after it, including the remaining pairs, becomes part of that value.

As root, or via sudo, stop the collector, wait for `lssrc` to report it `inoperative`, then start it with the file:

```bash
stopsrc -g oiqcollector
lssrc -g oiqcollector
startsrc -g oiqcollector -e "$(cat /etc/observiq-otel-collector.env)"
```

The collector also reads the file when it starts at boot.

{% hint style="warning" %}
Reinstalling the collector with the install script replaces `/etc/observiq-otel-collector.env` and keeps the old file as `/etc/observiq-otel-collector.env.<timestamp>.bak`. Copy your variables back into the new file after a reinstall.
{% endhint %}

To confirm the running collector has a variable, read its process environment as root, or via sudo:

```bash
ps eww $(lssrc -s observiq-otel-collector | awk 'NR == 2 { print $(NF - 1) }') | tr ' ' '\n' | grep DATACENTER
```

{% endtab %}

{% tab title="Containers" %}
Pass variables to a collector container the same way as for any other container: `-e NAME=value` with Docker, or an `env` entry in a Kubernetes container spec.
{% endtab %}
{% endtabs %}

### Reference Environment Variables in a Configuration

Reference a variable in any text parameter of a source, processor, destination, or extension:

```
${env:DATACENTER}
```

This is the syntax used throughout the OpenTelemetry documentation. Bindplane also accepts `${DATACENTER}`.

For example, to tag every log with the host's datacenter, add an Add Fields processor that sets the attribute `datacenter` to `${env:DATACENTER}`. Each collector running the configuration fills in the value from its own environment.

Keep these behaviors in mind:

* **Unset variables resolve to an empty value.** The collector still starts, and logs the warning `Configuration references unset environment variable`.
* **Variable names are case-sensitive on Linux.** `${env:datacenter}` and `${env:DATACENTER}` are different variables.
* **A literal `$` needs escaping.** Write it as `$$`, since a `$` followed by a name is read as a variable reference.
* **The rendered configuration shows `${DATACENTER}`.** Bindplane converts `${env:DATACENTER}` and `$DATACENTER` to `${DATACENTER}` when it renders the collector configuration, so that's what View Configuration shows. The collector resolves all of them the same way.

### Processor Previews

The preview in a processor's settings runs the processor in Bindplane, not on the collector. Bindplane doesn't have the collector's environment, so any value that references a variable shows up in that processor's preview as the reference itself, such as `${env:DATACENTER}`.

To see the value the collector actually uses, open the snapshot for the next step in the pipeline, such as the next processor or the destination. That snapshot comes from the collector, after the processor has run.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bindplane.com/how-to-guides/collector-management/use-environment-variables-in-collector-configurations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
