Search macro examples

Review these search macro use cases and their solutions.

Prerequisites

• See Use search macros in searches .
• See Define search macros in Settings.

Simple search macro with argument

The following set of partial searches 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 that allows you to pass an argument for the variable material between the slashes.

Steps

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

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

2. In the Arguments field, enter fragment as the argument.
3. Click Save.

You can insert `iis_search(fragment=TM)` into your search string to call the search macro for the TM fragment.

Preview your search to see the contents of your macro

Use the the search preview feature to see the contents of search macros that are embedded within the search, without actually running the search. When you preview a search, the feature expands all of the macros within the search, including macros that are nested within other macros.

Steps

1. Navigate to the Splunk Search page.
2. In the Search bar, type the default macro `audit_searchlocal(error)`.
3. Use the keyboard shortcut Command-Shift-E (Mac OSX) or Control-Shift-E (Linux or Windows) to open the search preview.
   The search preview displays syntax highlighting and line numbers, if those features are enabled.

   

4. (Optional) Copy a fragment of the search.
5. (Optional) Click Open in Search to run the expanded search in a new browser window.

Combine search macros and transactions

You can combine transactions and macro searches to simplify your transaction searches and reports. The following 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 that occur within 30 minutes of each other. Following is the definition of makesessions:

transaction clientip maxpause=30m

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

sourcetype=access_* | `makesessions`

The following 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

To build the same report with varying span lengths, save the report as a search macro with an argument for the span length. Name the macro pageviews_per_session(1). The macro references the original makesessions macro. Following is the definition for this macro:

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

When you insert the pageviews_per_session(1) macro into a search string, you use the argument to specify a span length.

`pageviews_per_session(span=1h)`

Validate arguments to determine whether they are numeric

The following example demonstrates search macro argument validation.

Steps

1. Select Settings > Advanced Search > Search Macros.
2. Click New Search Macro to create a new search macro.
3. For Name, enter newrate(2). The (2) indicates that the macro contains two arguments.
4. For Definiton, enter the following:
   

   eval new_rate=$val$*$rate$

   This definition includes the argument variables val and rate.
5. For the Arguments field, enter val and rate.
6. Enter a Validation expression that verifies that the value supplied for rate is numeric, as follows:
   isnum($rate$)
7. Enter the following Validation error message: "The rate value that you provided is not numeric. Enter a numeric rate value."
8. Click Save.

When another user includes the newrate(2) macro in a search, they might fill out the arguments like this: `newrate(revenue, 0.79)`.

If they leave the 0 out (`newrate(revenue, .79)`) the macro is invalid because the value .79 lacks a leading zero and is interpreted as a string. To ensure that the argument is read as a floating point number, the user should use the tonumber function as follows: `newrate(revenue, tonumber(.79))`