These docs are for Cribl Stream 4.16 and are no longer actively maintained.

See the latest version (4.17).

The JSON Unroll Function processes a JSON object string in the _raw field. It unrolls (explodes) an array of objects within this JSON into individual events, while inheriting the top-level fields from the original JSON object. This function is ideal for scenarios where processing individual items within an array is required while retaining the context provided by parent fields.

For efficiency, we recommend avoiding the JSON Unroll Function for certain types of data, such as CloudTrail, Office 365, or Kubernetes CloudWatch logs, which are often collected as JSON arrays. Instead, use an Event Breaker for inputs that support it. However, Event Breakers like JSON Array do not retain parent fields from the original JSON object. If retaining parent fields is critical, use the JSON Unroll Function or use a pre-processing Pipeline to extract parent fields before breaking events.

How the Function Works

​

When JSON Unroll runs, it parses the JSON object string in _raw into an internal field named __json. This internal field contains the full parsed structure of the event, including the array that you configure the Function to unroll. For example, if your array field is named data, the parsed JSON is available as __json.data, which you can reference in downstream Functions without reparsing _raw.

JSON Unroll then:

1. Locates the array at the configured Path within __json.
2. Iterates over each element in that array.
3. For each element, creates a new event that:
   • Inherits the top-level fields from the original JSON object. For example, date, name, or age.
   • Adds the current array element under the field specified in New name, or under its original field name if New name is left empty.
   • Serializes the resulting object back into _raw for the new event.

To inspect the parsed JSON and verify how JSON Unroll is working, enable Show Internal Fields in Data Preview. This exposes __json and other internal fields so you can see the parsed structure the Function is operating on.

Configuration

​

Filter: Filter expression (JavaScript) that selects data to feed through the Function. Defaults to true, meaning it evaluates all events.

Description: Simple description about this Function. Defaults to empty.

Final: Toggle on to stop feeding data to the downstream Functions. Default is toggled off.

Path: Path to array to unroll, such as foo.0.bar. This path is resolved against the parsed JSON stored in __json.

New name: The name that the exploded array element will receive in each new event. Leave empty to expand the array element with its original name.

Example

​

Assume you have an incoming event that has a _raw field as a JSON object string like this:

 {"date":"9/25/18 9:10:13.000 PM",
    "name":"Amrit",
    "age":42,
    "allCars": [
        { "name":"Ford", "models":[ "Fiesta", "Focus", "Mustang" ] },
        { "name":"GM", "models":[ "Trans AM", "Oldsmobile", "Cadillac" ] },
        { "name":"Fiat", "models":[ "500", "Panda" ] },
        { "name":"Blackberry", "models":[ "KEY2", "Bold Touch 9900" ] }
    ]
 }

With the following settings configured:

• Path: allCars
• New Name: cars

Your output events would look like:

Event 1:
{"_raw":"{"date":"9/25/18 9:10:13.000 PM","name":"Amrit","age":42,"cars":{"name":"Ford","models":["Fiesta","Focus","Mustang"]}}"}

Event 2:
{"_raw":"{"date":"9/25/18 9:10:13.000 PM","name":"Amrit","age":42,"cars":{"name":"GM","models":["Trans AM","Oldsmobile","Cadillac"]}}"}

Event 3:
{"_raw":"{"date":"9/25/18 9:10:13.000 PM","name":"Amrit","age":42,"cars":{"name":"Fiat","models":["500","Panda"]}}"}

Event 4:
{"_raw":"{"date":"9/25/18 9:10:13.000 PM","name":"Amrit","age":42,"cars":{"name":"Blackberry","models":["KEY2","Bold Touch 9900"]}}"}

Each element under the original allCars array is now placed in a cars field in its own event, inheriting original top level fields: date, name, and age. The parsed representation of each output event is also available under the internal __json field, which you can use in downstream Functions instead of reparsing _raw.

See Also

​

• The Cribl Knowledge Pack provides sample Pipelines that demonstrate converting a JSON string into an object literal, and validating JSON data against a schema.

Troubleshoot High Memory Usage or Slow Throughput

​

Issue: Pipelines are sluggish or Worker Nodes are hitting memory limits when processing Azure flow data.

Cause: Using the JSON Unroll Function on highly aggregated logs (like Azure VNet Flow logs) forces the Pipeline to hold massive objects in memory before they are split.

Solution: Migrate the unrolling logic from the Pipeline to the Source by applying the Azure VNet Flow Event Breaker. This segments the data before it hits the Pipeline, reducing resource overhead.