Splunk® Enterprise

Knowledge Manager Manual

Download manual as PDF

Download topic as PDF

Search macro examples

Here are some search macro use cases and their solutions.


Simple search macro with argument

Say you have a set of partial searches that are nearly identical:

sourcetype="iis" cs_username!="-" /TM/ .pdf

sourcetype="iis" cs_username!="-" /TD/ .pdf

sourcetype="iis" cs_username!="-" /TDB/ .pdf

You want to create a search macro that uses the common parts of this fragment and allows you to pass an argument for the variable material between the slashes.


  1. Create a search macro named iis_search(1) with this definition:

    sourcetype="iis" cs_username!="-" /$fragment$/ .pdf

  2. In the Arguments field, provide fragment as the argument.
  3. Save the new macro.

You can call the search macro for the TM fragment, by inserting `iis_search(fragment=TM)` into your search string.

Preview your search

You can preview a search before running it by using search expansion. Search expansion allows you to preview your search by expanding the entire search, including macros and nested macros, without running the search.



  1. Navigate to the Splunk Search page.
  2. In the Search bar, type the default macro `audit_searchlocal(error)`.
  3. Open the search expander by using the keyboard shortcut Command-Shift-E (Mac OSX) or Control-Shift-E (Linux or Windows).
    The search expander shows syntax highlighting and line numbers, if those features are turned on.
    This screen image shows the expanded default macro `audit_searchlocal(error)`.
  4. (Optional) Copy a fragment of the search.
  5. (Optional) Run your entire search by clicking Open in Search.

A new window opens with your expanded search.

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.

A search macro named makesessions defines a transaction session from events that share the same clientip value and which occur within 30 minutes of each other. Here is the definition of makesessions:

transaction clientip maxpause=30m

This search uses the makesessions search macro to take web traffic events and break them into sessions:

sourcetype=access_* | `makesessions`

This search uses the makesessions search macro to return 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 want to build the same report, but with varying span lengths, save it as a search macro with an argument for the span length. Here is the definition for this new macro, which is named pageviews_per_session(1). Note that this macro references the original makesessions macro.

sourcetype=access_* | `makesessions` | timechart $span$ sum(eventcount) as pageviews count as sessions

Now, you can specify a span length when you insert this into a search string:


Validating arguments to determine whether or not they are numeric

This example demonstrates search macro argument validation.


  1. Navigate to Settings > Advanced Search > Search Macros and click New to create a new search macro.
  2. Give the search macro the following Name: newrate(2). This name indicates that the macro contains two arguments.
  3. Give the newrate(2) search macro the following Definiton:

    eval new_rate=$val$*$rate$

    This definition includes the argument variables "val" and "rate".
  4. For the Argument field, list val and rate.
  5. The "rate" argument can only take numeric values, so you want to design a Validation expression that verifies that the value supplied for "rate" is numeric. Here is the expression you enter:
  6. Provide the following Validation error message: The rate value that you have provided is not numeric. Enter a numeric value.
  7. Save your search macro definition.

When you use the newrate(2) macro in a search, you might fill out the arguments like this: `newrate(revenue, 0.79)`.

Note that if you leave the 0 out (`newrate(revenue, .79)`) the macro will be invalid because the value ".79" lacks a leading zero and is interpreted as a string. To ensure the argument is read as a floating point numbers, use the tonumber function: `newrate(revenue, tonumber(.79))`

Define search macros in Settings
Dataset types and usage

This documentation applies to the following versions of Splunk® Enterprise: 6.6.0, 6.6.1, 6.6.2

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