Create and use search macros

Create and use search macros

Search macros are parametrized 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 > 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 mymacro required 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, $arg1$.
• 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.

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:

This search returns a report of the number of pageviews per session for each day:

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: