Splunk Search Macros

In this section, we are going to learn about Search Macros in the Splunk. We will also learn about How to Insert Macros to search string, preview search macros in search string, steps to create search macros, design a search macro definition.

Search macros are search processing language (SPL) chunks that can be reused and inserted into other searches. Search macros can be any part of a search, such as an evaluation statement or search word, and need not be in a complete order. Also, we can specify if the macro field takes any arguments.

Insert macros to search strings

When we put a search macro in a search string, place a character (') in the back tick before and after the macro name. That character is on the same key as the tilde (~) on most English-language keyboards. With this same syntax, we can reference a search macro within other search macros. For example, if we have a search macro named mymacro, when referenced in a search, it seems as follows:

sourcetype=access_* | `mymacro`

Macros are not expanded inside of quoted values. The search macro bar isn't extended in the example below.

"foo`bar`baz"

Preview search macros in search strings

Check the contents of our search macro using the following keyboard shortcut from the Search bar on the Search page:

• Control+Shift+E(Mac OSX)
• Control+Shift+E(Linux or Windows)

The shortcut opens a preview of the extended search string, which contains all nested search macros and saved results. If syntax marking or line numeration is allowed, those features will also appear in the preview.

We can copy portions of the search string to be expanded. Now, to run the expanded search string in a new window, we can click Open in Search Show Our results preview.

Search macros that contain generating commands

By using a search macro in a search string, consider if the macro extends to an SPL string beginning with a request, metadata, inputlookup, pivot, and tstats order. We need to place a pipe character in front of the search macro when it does.

For example, if we know that the search macro mygeneratingmacro starts with the command tstats, we would insert it as follows in our search string:

| `mygeneratingmacro`

When search macros take arguments

If arguments are taken from our search macro, define those arguments when inserting them in the macro into the search string in the Splunk. For an instance, if the search macro argmacro(2) contains two integer arguments, we could have inserted the macro as follows: 'argmacro(120,300)' in our search string.

If quotes are included in our search macro argument, escape the quotes in our search when calling the macro. E.g., if we pass a quoted string as our macro argument, we'll use: 'mymacro('He said \'hello!\').'

Our search macro definition can include the following:

• Expression of validation which determines whether the arguments we enter are valid.
• A message for the validation error that appears when we give invalid arguments.

Steps to create Search Macros.

1. Select Settings > Advanced Search > Search macros.
2. Click Newto create a search macro.
3. Check the Destination app and verify that the app we want to limit our search macro to is set to. If we want to confine our search macro to a different app, pick a different app from the Destination app list.
4. Enter a unique Search Macro Name. If an argument is included in our search macro, append the number of arguments to the name. For example, if our mymacro quest has two arguments, call it mymacro(2).
5. In Description, please enter the search string to which the macro extends when referencing it in a specific search.
6. Click Use definition based on an assessment? To imply that the Description value is an eval expression, which returns a string to which the macro quest extends.
7. Enter any Macro Search Arguments. That is a comma-delimited string of names of arguments. The names of arguments may contain only alphanumeric characters (a-Z, A-Z, 0-9), underscores, and dashes. The string can not contain repetitions of the names of the arguments.
8. Enter a Validation expression that verifies acceptability of the argument values used to invoke the search macro. The expression "validation" is an expression corresponding to a Boolean or a string value.
9. (Optional) If we have defined a validation expression, enter a Validation error message. This message will appear when the validation expression fails the argument values which invoke the search macro.
10. Click Save to save our search macro.

Design a search macro definition

The basic part of a search macro is its meaning, which is the SPL's chunk to which the macro extends when we refer to it in another search.

If there are variables in our search macro definition, then the macro user must input the variables into the definition of search macro as tokens with dollar signs on either side. For instance, $arg1 $might be the first argument in the definition of a search macro.

Pipe characters and generating commands in macro definitions

When we use generating commands in Splunk web like search, inputlookup, or tstats in searches, put them at the start of the search, with a leading pipe character.

If we want our search macro to use a generating command, remove the leading pipe character from the macro definition. Place it at the start of the search string that we are inserting the search macro into, in front of the search macro reference.

For instance, we have a search macro named mygeneratingmacro with the definition of:

tstats latest(_time) as latest where index!=filemon by index host source sourcetype

The concept of mygeneratingmacro starts with the generating command tstats. Instead of preceding tstats with a pipe character in the macro description, we put the pipe character in the search string, before the search macro reference. For instance:

| `mygeneratingmacro`

Validate search macro arguments.

If we create a search macro that contains arguments to be entered by the user, we will create a Validation expression that will decide if the user's arguments are true. We may describe an error message of validation that occurs when validation of search macro arguments fails.

The expression of validation has to be an expression evaluating to a Boolean or a string. If the expression for validation is boolean, validation is successful if the expression for validation returns true. If it returns false or returns null, it fails validation.