Script

Control Flow

Synopsis

Executes custom scripts and optimized built-in functions to transform and manipulate log data.

Schema

- script:
    source: <string>
    lang: <string>
    params: <map[string]any>
    function: <string>
    description: <text>
    filter: <script>
    if: <script>
    id: <ident>
    ignore_failure: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
source	Y*	-	Inline script code. Read by the golang/go and javascript/js engines
lang	Y	-	Scripting language: "golang" (or "go"), "javascript" (or "js"), or "vmetric"
params	N	-	Map of parameters available to the script
function	Y*	-	Name of the predefined function to run. Required by, and only used by, the vmetric engine
description	N	-	Explanatory note
filter	N	-	Cribl-style JavaScript truthiness expression evaluated after if. A falsy result silently skips the processor. Distinct from if, which uses the native expression language
if	N	-	Condition to run
ignore_failure	N	false	See Handling Failures
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

* = source for the golang/go and javascript/js engines, function for vmetric. lang itself is genuinely required: an unrecognized value fails with unsupported script language.

Details

warning

This processor runs on the Director only. The Agent binary is built without it, so an Agent-side pipeline that configures it fails at runtime with a not supported error rather than skipping the step. Put it in a pipeline the Director runs — a route pipeline or a target postprocessing pipeline — not in an Agent's preprocessing chain.

The processor supports three script engines, selected with lang. Each has its own reference page under Scripting.

JavaScript

lang: javascript (or js) runs a full script body in a sandboxed JavaScript interpreter. The event is exposed as __e: use __e.field for simple names and __e['field.name'] for names containing dots. Remove a field with delete __e['field']. Values supplied through params arrive as a params object.

A large function library is available under a C namespace — network tests, text parsing, time formatting, masking, encoding and CSV lookups.

- script:
    lang: js
    source: |
        __e.normalized = __e.field.toLowerCase();

Full reference: JavaScript.

Go

lang: golang (or go) runs a script through a sandboxed bytecode VM. The syntax is Go-like, but this is not Go and the Go standard library is not available. The event is bound to a global named event, and five modules — text, math, times, json and rand — are available through import.

- script:
    lang: go
    source: |
        text := import("text")
        event.normalized = text.to_lower(event.field)

Full reference: Go.

Built-in

lang: vmetric calls one of thirteen functions compiled into the product, named in the function field. These skip script compilation entirely and should be preferred over an equivalent custom script.

- script:
    lang: vmetric
    function: getNetworkTransport()

Full reference: Built-in Functions.

Filter and Condition

filter and if both gate the processor, and they take different languages. filter is a JavaScript expression evaluated after if, in which a bare field name resolves against the event; if uses DataStream's own expression language. A falsy filter skips the processor silently.

Failure Behavior

The two script engines differ in what a partial failure leaves behind. JavaScript writes to the event as the script runs, so a script that throws halfway leaves its earlier changes in place. Go writes the event back only on success, so a failed script changes nothing.

Examples

Go

Classify by a numeric threshold...

- script: lang: go source: | confidence := event["threat.indicator.confidence"] if !is_undefined(confidence) && confidence > 70 { event["threat.level"] = "high" }

JavaScript

Normalize a field and tag it with a threshold from params...	{ "user": "John.Doe", "score": 85 } - script: lang: js params: threshold: 70 source: | __e.user = __e.user.toLowerCase(); __e.high = __e.score > params.threshold;
Fields are read and written directly on the event via __e...	{ "user": "john.doe", "score": 85, "high": true }

Built-in

Process time fields efficiently...

- script: lang: vmetric function: processTimeFields("log.time", "log.timestamp", "log.times")

Composite

Combine a built-in function with custom logic...

- script: lang: vmetric function: getNetworkTransport() - script: lang: js source: | const t = __e['network.transport']; if (t === 'tcp' || t === 'udp') { __e['network.type'] = 'ip_traffic'; }