Unroll

The Unroll processor operates on log records whose body field is a list (array). It expands the record into multiple log records, one per element in the array, while preserving the original timestamp, attributes, and resource attributes. It runs on logs only.

Supported Telemetry Types

Metrics	Logs	Traces
	✓

Configuration

The Unroll processor processes any log record whose body is an array, expanding each element into its own record. Records whose body is not an array pass through unchanged.

Parameter	Type	Required	Default	Description
Recursive	Boolean	No	false	Recursively unroll nested arrays until no array values remain. When disabled, only the top-level array is unrolled and any nested array elements are emitted as-is. When enabled, an element that is itself an array is unrolled again, repeating until no record has an array body.

Examples

Unroll an array body into separate log records

Given a single log record with an array body:

body: ['a', 'b', 'c']

the processor emits three log records, each carrying one element as its body (a, b, c). Each new record keeps the original record's timestamp, attributes, and resource attributes.

Add the processor to a logs pipeline with the default settings:

apiVersion: bindplane.observiq.com/v1
kind: Processor
metadata:
  name: unroll
spec:
  type: unroll
  parameters:
    - name: recursive
      value: false

Unroll nested arrays recursively

By default only the top-level array is unrolled, so a nested array is emitted as a single record whose body is still an array. Given:

body: ['a', ['b', 'c'], 'd']

with recursive: false the processor emits three records with bodies a, ['b', 'c'], and d — the second record still holds an array. With recursive: true the processor keeps unrolling nested arrays until no array bodies remain, emitting four records with bodies a, b, c, and d.

apiVersion: bindplane.observiq.com/v1
kind: Processor
metadata:
  name: unroll
spec:
  type: unroll
  parameters:
    - name: recursive
      value: true

Configuration Tips

• The processor only acts on records whose body is an array. Records with a scalar or map body are left untouched.
• Expanding a large array multiplies the log record count, which increases downstream processing and storage. A record that expands into many entries can also cause UI rendering slowdowns when previewing the pipeline. Apply it where the array is bounded, or pair it with a filter to drop unwanted elements.
• Enable recursive only when the body contains nested arrays that you want flattened completely. With deeply nested data, recursive unrolling multiplies the record count at every level, so bound the input where you can.
• To produce array bodies in the first place (for example by splitting a field), pair Unroll with a Transform processor upstream.

Troubleshooting

Records pass through unchanged

Symptoms: the log count does not increase after the processor runs.

Solutions:

1. Confirm the body field is actually an array. A scalar or map body is left as-is.
2. Check that earlier processors in the pipeline have not already flattened or replaced the array body.

UI preview is slow or unresponsive

Symptoms: the pipeline preview hangs or renders slowly after adding the processor.

Solutions:

1. A record expanding into a very large number of entries can overwhelm the UI preview. Test against a smaller sample, or bound the array size upstream before unrolling.

Standalone Processor

apiVersion: bindplane.observiq.com/v1
kind: Processor
metadata:
  name: unroll
spec:
  type: unroll
  parameters:
    - name: recursive
      value: false

Related Resources

• Unroll Processor — OpenTelemetry Collector Contrib
• Transform processor