Splunk® Enterprise

Knowledge Manager 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

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.

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)`. 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.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5


Also note that as of 6.5.0 (maybe older) splunk is smart enough not to need the `tonumber` call that is mentioned in your last sentence note (although it definitely was necessary at some point because I remember answering this question about it, which is the basis for your note: https://answers.splunk.com/answers/387487/macro-validation-expression-error.html)

January 16, 2017

There is a highlighting error; this text in step #6 should be called out as "code" (to match the other steps):
The rate value that you have provided is not numeric. Enter a numeric value

January 16, 2017

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