Script

Control Flow Elastic Compatible

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

Field	Required	Default	Description
source	Y	-	Inline script code
lang	N	"painless"	Scripting language ("painless", "golang", 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.

Painless

While there is support for Elasticsearch Painless for convenience, this may not cover all the features, and has an overhead.

script:
  - lang: painless
    source: |
      ctx.normalized = ctx.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") } } } }

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...

processors: - 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" } } }