Cribl LogStream – Docs

Cribl LogStream Documentation

Questions? We'd love to help you! Meet us in #Cribl Community Slack (sign up here)
Download entire manual as PDF - v2.4.5

Eval

Description

The Eval Function adds or removes fields from events. (In Splunk, these are index-time fields.)

Usage

Filter: Filter expression (JS) that selects data to be fed through the Function. Defaults to true, meaning that all events will be evaluated.

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

Final: If true, stops data from being fed to the downstream Functions. Defaults to No.

Evaluate fields: Set of key/value pairs to add. The left-hand side input (Name) is the key name. The right-hand side input (Value Expression) is a JS expression to compute the value – this can be a constant. Nested addressing is supported. Strings intended to be used as values must be single- or double-quoted. (For details, see Introduction to Expression Syntax.)

Keep fields: List of fields to keep. Wildcards (*) and nested addressing are supported. Takes precedence over Remove fields (below). To reference a parent object and all children requires using the (*) wildcard. For example, if _raw is converted to an object then use _raw* to refer to itself and all children.

Remove fields: List of fields to remove. Wildcards (*) and nested addressing are supported. Cannot remove fields matching Keep fields. Cribl LogStream internal fields that start with __ (double underscore) cannot be removed via wildcard. Instead, they need to be specified individually. For example, __myField cannot be removed by specifying __myF*.

Using Keep and Remove

A field matching an entry in both Keep (wildcard or not) and Remove will not be removed. This is useful for implementing “remove all but” functionality. For example, to keep only _time, _raw, source, sourcetype, host, we can specify them all in Keep, while specifying * in Remove.

Negated terms are supported in both Keep fields and Remove fields. The list is order-sensitive when negated terms are used. Examples:

  • !foobar, foo* means "All fields that start with 'foo' except foobar."
  • !foo*, * means "All fields except for those that start with 'foo'."

Examples

Scenario A: Create field myField with static value of value1:

  • Name: myField
  • Value Expression: 'value1'

Scenario B: Set field action to blocked if login==error:

  • Name: action
  • Value Expression: login=='fail' ? 'blocked' : action

Scenario C: Create a multivalued field called myTags. (i.e., array):

  • Name: myTags
  • Value Expression: ['failed', 'blocked']

Scenario D: Add value error to the multivalued field myTags:

  • Name: myTags
  • Value Expression: login=='error' ? [...myTags, 'error'] : myTags

(The above expression is literal, and uses JavaScript spread syntax.)

Scenario E: Rename an identification field to the shorter ID – copying over the original field’s value, and removing the old field:

  • Name: ID
  • Value Expression: identification
  • Remove Field: identification

📘

See Ingest-time Fields for more examples.

Advanced Usage Notes

Execution Without Assignment

The Eval Function can execute expressions without assigning their value to the field of an event. You can do this by simply leaving the left-hand side input empty, and having the right-hand side do the assignment.

Example: Parse and Merge to Existing Field

Object.assign(foo, JSON.parse(bar), JSON.parse(baz)) on the right-hand side (and left-hand side empty) will JSON-parse the strings in bar and baz, merge them, and assign their value to foo, an already existing field.

Example: Reference Event with __e

To parse JSON, enter Object.assign(__e, JSON.parse(_raw)) on the right-hand side (and left-hand side empty). __e is a special variable that refers to the (context) event within a JS expression. In this case, content parsed from _raw is added at the top level of the event.

Set/Unset Control Fields

You can also use the Eval Function to set and unset control fields (e.g., _TCP_ROUTING in Splunk), via this syntax: _ctrl.<name>. Control fields can be referenced only on the left-hand side of Add. (I.e., they cannot be read or used on the right-hand side, and cannot be referenced in Remove.)

To unset/delete a control field, set its value to undefined. These fields are normally not needed for event computations, and Cribl suggests that only experts should modify them. Please reach out to Cribl if you need help with this topic.

Updated 2 months ago

Eval


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.