Use search macros in Splunk Light
Search macros are reusable chunks of Search Processing Language (SPL) that you can insert into other searches. Search macros can be any part of a search, such as an eval statement or search term, and do not need to be a complete command. You can also specify whether or not the macro field takes any arguments.
Insert search macros into search strings
To include a search macro in a search string, use the back tick character ( ` ). On most English-language keyboards, this character is located on the same key as the tilde (~). You can also reference a search macro within other search macros using this same syntax. If you have a search macro named
mymacro it looks like this when referenced in a search:
sourcetype=access_* | `mymacro`
Macros inside of quoted values are not expanded. In the following example, the search macro
bar is not expanded.
Search macros that contain generating commands
Generating commands like
tstats always appear at the start of search strings with a leading pipe character. If the definition of your search macro starts with a generating command, the search macro should be inserted into the start of your search string, with a leading pipe character before it. Do not put a leading pipe character in the definition of search macros that begin with generating commands. Here is an example:
When search macros take arguments
If your search macro takes arguments, you define those arguments when you insert the macro into the search string. For example, if the search macro
argmacro(2) includes two arguments that are integers, you might have insert the macro into your search string like this:
If your search macro argument includes quotes, escape the quotes when you call the macro in your search. For example, if you pass a quoted string as the argument for your macro, you would use:
`mymacro("He said \"hello!\"")`.
Your search macro definition can include a validation expression that determines whether the arguments you have entered are valid, and a validation error message that you see when you provide invalid arguments.
Define search macros
- Learn how to Insert search macros into search strings.
- Understand how to design a search macro definition.
- If your search macros require the search writer to provide argument variables, you can design validation expressions that tell you when invalid arguments have been submitted. See Validate search macro arguments.
- In the sidebar menu, go to Knowledge > Search macros.
- Click New to create a new search macro.
- Change the Destination App to the app you want to restrict your search macro to if it has defaulted to the wrong app.
- Provide a unique Name for the search macro.
If your search macro includes an argument, indicate this by appending the number of arguments to the name. For example, if your search macro
mymacroincludes two arguments, name it
- In Definition, provide the search string that the macro expands to when you reference it in another search.
- (Optional) Select Use eval-based definition? to indicate that the Definition value is an
- (Optional) Provide Arguments as appropriate for your search macro. This is a comma-delimited string of argument names without repeated elements. Argument names may only contain alphanumeric characters (a-Z, A-Z, 0-9), underscores, and dashes.
- (Optional) Provide a Validation expression that verifies whether the argument values used to invoke the search macro are acceptable. The validation expression is an
evalexpression that evaluates to a boolean or a string.
- (Optional) Provide a Validation error message if you defined a validation expression. This is the message that returns when the argument values that invoke the search macro fail the validation expression.
- Click Save to save your search macro.
Design a search macro definition
The fundamental part of a search macro is its definition, which is the SPL chunk that the macro expands to when you reference it in another search. There are a few things that you should know before you design a search macro definition.
If your search macro definition has variables that must be input by the macro user, put them in the definition as tokens that have dollar signs wrapped around them. For example,
$arg1$ could be the first argument in a search macro definition.
Pipe characters and generating commands in macro definitions
When you use generating commands such as
tstats in searches, you always put them at the start of the search, with a leading pipe character.
However, if you want your search macro to use a generating command, you should remove the leading pipe character from the macro definition, and instead place it at the start of the search string that you are inserting the search macro into, in front of the search macro reference.
For example, say you have a search macro named
mygeneratingmacro that has the following definition:
tstats latest(_time) as latest where index!=filemon by index host source sourcetype
The definition of
mygeneratingmacro begins with the generating command
tstats. Instead of preceding
tstats with a pipe character in the macro definition, you put the pipe character in the search string, ahead of the search macro reference, like this:
Eval expressions in macro definitions
To create macro definitions that are
eval command expressions, select Use eval-based expression?. This setting specifies that the search macro definition is an eval expression that returns a string. This string is what the macro ultimately expands to.
Validate search macro arguments
When you define a search macro that includes arguments that must be entered by the user, you can define a Validation expression that determines whether the arguments supplied by the user are valid or not. You can also define a Validation error message that displays when search macro arguments fail validation.
The validation expression must be an
eval expression that evaluates to a boolean or a string. If the validation expression is boolean, validation succeeds when the validation expression returns "true". If it returns "false" or is null, validation fails.
If the validation expression is not boolean, validation succeeds when the validation expression returns null. If it returns a string, validation fails.
Use lookups in Splunk Light
Check search and scheduler activity in Splunk Light
This documentation applies to the following versions of Splunk® Light: 6.5.0, 6.5.1, 6.5.2, 6.5.3, 6.5.1612 (cloud service only), 6.6.0, 6.6.1, 6.6.2, 6.6.3, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6