> 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/coalesce.md).

# Coalesce

The Coalesce processor consolidates fields that arrive under different names into one standard field. You give it an ordered list of places a value might live, and the first non-empty source populates the target.

### Supported Telemetry Types

| Logs | Metrics | Traces |
| ---- | ------- | ------ |
| ✓    | ✓       | ✓      |

The processor runs only on the signals you select in **Choose Telemetry Type**. Each selected signal is configured independently in its own section.

### Configuration

#### Basic Configuration

<figure><img src="/files/hkX62IgDRSEpoYupUMuH" alt="Bindplane docs - Coalesce - image 1"><figcaption></figcaption></figure>

You give the processor an ordered list of source fields and a single field to write the first non-empty value to.

| Parameter                      | Type               | Required | Default      | Description                                                                                                                                                              |
| ------------------------------ | ------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Choose Telemetry Type          | Telemetry Selector | No       | (none)       | The signals (Logs, Metrics, Traces) this processor applies to. Each selected signal is configured in its own section.                                                    |
| Condition                      | OTTL Condition     | No       | (empty)      | An OTTL condition that must be true for the processor to run. Empty applies it to every record of the selected signal.                                                   |
| Coalesce From (priority order) | Source rows        | Yes      | —            | The ordered list of source fields. At least one is required. Each row picks a context and a field key; the first non-empty source populates the target. Drag to reorder. |
| Coalesce To                    | Enum               | Yes      | `Attributes` | Where the result is written: `Attributes` or `Body`. Logs only; Metrics and Traces always write to attributes.                                                           |
| Attributes Field / Body Field  | OTTL Field         | Yes      | (empty)      | The single field that receives the coalesced value. Which one shows depends on Coalesce To.                                                                              |

#### Source Contexts by Signal

| Signal  | Available source contexts        |
| ------- | -------------------------------- |
| Logs    | `body`, `attributes`, `resource` |
| Metrics | `attributes`, `resource`         |
| Traces  | `attributes`, `resource`         |

`body` is offered for Logs only. Metrics and Traces have no body, and they always write the result to attributes (no Coalesce To choice).

### Examples

#### Normalizing a timestamp that arrives under several names

<figure><img src="/files/brTEDj2JMHQOJR07F8IW" alt="Bindplane docs - Coalesce - image 2"><figcaption></figcaption></figure>

A timestamp may show up as `attributes["time"]`, `body["ts"]`, or `resource.attributes["event.time"]` depending on the source. Listing all three in priority order coalesces them into a single `attributes["timestamp"]`: the processor checks each in order and writes the first non-empty one, leaving the target untouched once it is set.

#### Normalize severity fields on logs

Severity may arrive as `body["sev"]`, `body["severity"]`, or `body["level"]`. Listing them in priority order coalesces the first non-empty one into `attributes["severity"]`, only on records whose body is a map.

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Processor
metadata:
  name: coalesce-severity
spec:
  type: coalesce_v2
  parameters:
    - name: telemetry_types
      value:
        - Logs
    - name: log_condition
      value: IsMap(body)
    - name: log_sources
      value:
        - context: body
          key: sev
        - context: body
          key: severity
        - context: body
          key: level
    - name: to_log_base
      value: Attributes
    - name: to_log_attributes
      value: severity
```

### Configuration Tips

#### Order is priority

* The list is evaluated top to bottom and the first non-empty source wins, so put the most authoritative source first. Once the target is populated, later sources are ignored for that record.
* An empty Coalesce From list is rejected; add at least one source.

### Troubleshooting

#### The target field isn't being populated

**Symptoms:** Records pass through and the target field stays empty.

**Solutions:**

1. Confirm at least one source in the list actually resolves on the record (right context, exact key).
2. Check that the target field isn't already set upstream; coalesce only writes when the target is empty.
3. If a Condition is set, confirm it evaluates true for the records you expect to transform.

### Standalone Processor

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Processor
metadata:
  name: coalesce-timestamp
spec:
  type: coalesce_v2
  parameters:
    - name: telemetry_types
      value:
        - Logs
    - name: log_sources
      value:
        - context: attributes
          key: time
        - context: body
          key: ts
        - context: resource
          key: event.time
    - name: to_log_base
      value: Attributes
    - name: to_log_attributes
      value: timestamp
```

### What Changed in This Version

This replaces the original Coalesce processor, which is now deprecated. Existing configurations keep using the deprecated processor until you migrate.

* **First non-empty wins.** The original applied each source in order with an action that defaulted to `upsert`, so the last non-empty source overwrote the target (last-wins). The v2 writes the **first** non-empty source instead (SQL `COALESCE` semantics) and leaves the target untouched once set.
* **Multiple locations in one list.** Sources can mix `body`, `attributes`, and `resource` in a single priority-ordered list, instead of coalescing from a single base.
* **Reorderable.** Sources can be dragged to set priority order.

### Related Resources

* [OTTL `set` function](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/pkg/ottl/ottlfuncs/README.md#set)

### Bindplane Resources

* [Concat processor](/integrations/processors/concat.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/coalesce.md?ask=<question>&goal=<endgoal>
```

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