Create and use search macros
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Create and use search macros
Search macros are chunks of a search that you can reuse in multiple places, including saved and ad hoc 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.
This topic discusses how to create and then use search macros via Splunk Web. For more information about how and why to use search macros, see the Design macro searches in the Knowledge Manager manual.
Create search macros in Splunk Web
In Manager > Advanced Search > Search macros, click "New" to create a new search macro.
Define the search macro and its arguments
Your search macro can be any chunk of your search string or search command pipeline that you want to re-use as part of another search.
- Destination app is the name of the app you want to restrict your search macro to; by default, your search macros are restricted to the Search app.
- Name is the name of your search macro, such as
mymacro. If your search macro takes an argument, you need to indicate this by appending the number of arguments to the name; for example, if
mymacrorequired two arguments, it should be named
mymacro(2). You can create multiple search macros that have the same name but require different numbers of arguments:
foo, foo(1), foo(2), etc.
- Definition is the string that your search macro expands to when referenced in another search. If the search macro includes arguments, they are filled in and wrapped by dollar signs; for example,
- If Eval Generated Definition? is checked, then the 'Definition' is expected to be an eval expression that returns a string that represents the expansion of this macro.
- Arguments are a comma-delimited string of argument names. Argument names may only contain the characters: alphanumeric 'a-Z, A-Z, 0-9'; underscore '_'; and dash '-'. This list should not contain any repeated elements.
If a macro definition includes a leading pipe character ("|"), you may not use it as the first term in searches from the UI. Example: "| metadata type=sources". The UI does not do the macro expansion and cannot correctly identify the initial pipe to differentiate it from a regular search term. The UI constructs the search as if the macro name were a search term, which after expansion would cause the metadata command to be incorrectly formed and therefore invalid.
If a macro argument includes quotes, you need to escape the quotes when you call the macro in your search. For example, if you wanted to pass a quoted string as your macro's argument, you would use:
`my-macro("He said \"hello!\"")`.
Validate your argument values
You can verify that the argument values used to invoke the search macro are acceptable. How to invoke search macros are discussed in the following section, "Apply macros to saved and ad hoc searches".
- Validation Expression is a string that is an 'eval' expression that evaluates to a boolean or a string.
- If the validation expression is a boolean expression, validation succeeds when it returns true. If it returns false or is null, validation fails, and the Validation Error Message is returned.
If the validation expression is not a boolean expression, it is expected to return a string or NULL. If it returns null, validation is considered a success. Otherwise, the string returned is rendered as the error string.
Apply macros to saved and ad hoc searches
To include a search macro in your saved or ad hoc searches, use the left quote (also known as a grave accent) 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.
Note: Do NOT use the straight quote character that appears in the same key as the double quote (").
Example - Combine search macros and transactions
Transactions and macro searches are a powerful combination that you can use to simplify your transaction searches and reports. This example demonstrates how you can use search macros to build reports based on a defined transaction.
Here, a search macro, named "makesessions", defines a transaction session from events that share the same clientip value that occurred within 30 minutes of each other:
transaction clientip maxpause=30m
This search takes pageview events and breaks them into sessions, using the "makesessions" search macro:
eventtype=pageview | `makesessions`
This search returns a report of the number of pageviews per session for each day:
eventtype=pageview | `makesessions` | timechart span=1d sum(eventcount) as pageviews count as sessions
If you wanted to build the same report, but with varying span lengths, just save it as a search macro with an argument for the span length. Let's call this search macro, "pageviews_per_second(1)":
eventtype=pageview | `makesessions` | timechart $spanarg$ sum(eventcount) as pageviews count as sessions
Now, you can specify a span length when you run this search from the Search app or add it to a saved search:
This documentation applies to the following versions of Splunk: 4.1 , 4.1.1 , 4.1.2 , 4.1.3 , 4.1.4 , 4.1.5 , 4.1.6 , 4.1.7 , 4.1.8 , 4.2 , 4.2.1 , 4.2.2 , 4.2.3 , 4.2.4 , 4.2.5 , 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6