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>
    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
lang	Y	-	Scripting language: "golang" (or "go"), "javascript" (or "js"), or "vmetric"
params	N	-	Map of parameters available to the script
function	N	-	Name of predefined function for vmetric mode
description	N	-	Explanatory note
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

Details

The processor supports three scripting modes:

Native Go

Go scripts provide full access to all of Go's features, and therefore is the recommended language for complex scenarios.

- script:
    lang: golang
    source: |
        package main
        
        func main() {
          if val, ok := logEntry["field"].(string); ok {
            logEntry["normalized"] = strings.ToLower(val)
          }
        }

note

Scripts are cached using xxHash for performance, reusing compiled versions. Go scripts can use all the standard library functions supported by our interpreter.

JavaScript

JavaScript scripts run a full script body and offer a convenient option for logic that does not require Go. The current event is exposed through the reserved __e variable: use __e.field for simple field names and __e['field.name'] (bracket notation with quotes) for names containing dots or other special characters. Remove a field with delete __e['field']. Any values supplied through params are available as a params object.

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

Built-in

Optimized implementations of common VirtualMetric functions that bypass script interpretation. These should be preferred over equivalent custom scripts.

Function	Description
getNetworkTransport()	Resolves IANA protocol numbers to transport names
sumFields(targetField, firstField, secondField)	Adds numeric fields using type handling
sumNetworkBytes()	Calculates the total number of network bytes
sumNetworkPackets()	Calculates the total number of network packets

Examples

Native Go

Process nested fields with Go...

- script: lang: golang source: | package main func main() { val, err := getField(logEntry, "threat.indicator.confidence") if err == nil { if confidence, ok := val.(float64); ok { if confidence > 70 { setField(logEntry, "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 built-in functions with custom logic...

- script: lang: vmetric function: getNetworkTransport() - script: lang: golang source: | package main func main() { if transport, ok := logEntry["network.transport"].(string); ok { if transport == "tcp" || transport == "udp" { logEntry["network.type"] = "ip_traffic" } } }