Cribl LogStream – Docs

Cribl LogStream Documentation

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

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.

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 a multivalued field myTags:

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

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

Note 1

The Eval Function has the ability to 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.

  • Simple Example: 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.

  • Another Example: 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.

Note 2

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 modifying them is suggested to be done only by experts. Please reach out to Cribl if you need help with this topic.

Updated 5 days 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.