Splunk® Enterprise

Search Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

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.

Create search macros in Splunk Web

In Settings > 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 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 requires the user to input arguments, they are tokenized and indicated by wrapping dollar signs around the arguments; for example, $arg1$. The arguments values are then specified when the search macro is invoked.

  • 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.
  • 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.

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 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 web traffic events and breaks them into sessions, using the "makesessions" search macro:

sourcetype=access_* | `makesessions`

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

sourcetype=access_* | `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)":

sourcetype=access_* | `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:

`pageviews_per_second(span=1h)`

PREVIOUS
Scheduling searches
  NEXT
Export search results

This documentation applies to the following versions of Splunk® Enterprise: 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15


Comments

@Rafrey: Thanks for reporting this issue. The "here" link should now show you links to the current version of the topic, which now exists in the Knowledge Manager Manual.

Mness, Splunker
March 7, 2016

The link at the top of this page to the most recent version at http://docs.splunk.com/Documentation/Splunk/latest/Search/Usesearchmacros is broken. Are search macros no longer supported past version 6.2.8 or is the documentation missing?

Rafrey
March 7, 2016

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters