Commands and the Alert Action
The three ways guest code is invoked. exec and execgen are search
commands, typed into a search bar; execalert is an alert action, configured
on a saved search. All three run the same guest code against the same daemon,
so what you learn about one applies to the others.
Exec
Streaming command. Runs guest code over every event flowing through the pipeline.
... | exec (inline=<python> | function=<name>) [batch_size=<n>] [autocast=<mode>] [<key>=<value> ...]
| Argument | Default | Description |
|---|---|---|
inline | Python source to run for each micro-batch. | |
function | Name of a .wasm component in functions/. The .wasm suffix is optional. | |
batch_size | 32 | Events handed to the guest per call. |
autocast | false | Infer types for field values: true, false or strict. See Inline Python. |
<key>=<value> | Anything else is passed to guest code as params. See Parameters from the search. |
inline and function are mutually exclusive. Exactly one is required.
Reports itself to Splunk as type = streaming, so it may be distributed to
indexers. Add local = true to the commands.conf stanza to pin it to the
search head.
index=web | exec inline="for e in events: e['host'] = e['host'].lower()"
index=web | exec function=enrich batch_size=256
Execgen
Generating command. Produces events rather than transforming them, so it must be first in the pipeline.
| execgen (inline=<python> | function=<name>)
Same arguments as exec. The guest is called once with an empty events
list; whatever it leaves in events becomes the search results.
Reports itself as type = stateful, which means it runs on the search head
and is not distributed.
| execgen inline="events = [{'i': i, 'square': i * i} for i in range(100)]"
Execalert
Alert action. Runs guest code over a scheduled search's results after it fires.
Configured on a saved search rather than typed into a search bar:
action.execalert = 1
action.execalert.param.inline = for e in events: e['seen'] = 1
| Parameter | Description |
|---|---|
param.inline | Python source to run for each micro-batch of result rows. |
param.function | Name of a .wasm component. |
param.autocast | Type inference: true, false or strict. Defaults to off. |
Mutually exclusive, one required. Splunk writes unset parameters as empty strings, which are treated as absent.
An alert with no results still calls the guest once with an empty events
list, so side-effect-only actions run.
See Alert actions.
Field Semantics
Everything is a string. Splunk's data model is text. Convert before doing
arithmetic, or set autocast=true to have types inferred for you.
Multivalue fields are lists. A field Splunk holds as multivalue arrives as a list of strings, and a list you assign becomes a multivalue field.
Missing fields are absent. Not None, not empty string. Use .get().
Search-time extracted fields must be referenced first. Splunk only
materialises extracted fields that something in the pipeline mentions, and
guest code is opaque to it. Reading raw events directly needs an explicit
| fields ... before the command:
index=auth | fields _time user src_ip action | exec inline="..."
This does not apply after stats, table or eval, which have already
materialised what they produce.
Field order is preserved from input to output, and fields your code adds are appended in the order it adds them.
Values are converted on the way out as follows:
| Python type | Splunk field |
|---|---|
str | As-is |
int, float | Decimal string |
bool | 1 or 0 |
None | Empty |
list of 1 | Scalar |
list of many | Multivalue |
dict | Compact JSON |
bytes | Base64 |
datetime, date | ISO 8601 |
set, tuple | Multivalue |
| Anything else | str(value) |
Errors
Errors reach the search as FATAL: Error in 'exec' command: <message>.
Splunk's CLI hides these under -output json. Use the default output to see
them:
splunk search '| makeresults | exec inline="1/0"' -auth ...
FATAL: Error in 'exec' command: ZeroDivisionError: division by zero
A syntax error is reported before any events are processed. A runtime error fails the batch it occurred in; earlier batches have already been emitted.
Exit Behaviour
The command exits non-zero and reports through the protocol when it cannot start: unknown function, unparseable arguments, or a daemon it cannot reach or start. Splunk shows the message on the search rather than "external search command exited unexpectedly".