Search macro examples
Review these search macro use cases and their solutions.
Prerequisites
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
- Create a search macro named
iis_search(1)
with the following definition:sourcetype="iis" cs_username!="-" /$fragment$/ .pdf
- In the Arguments field, enter fragment as the argument.
- 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
- Navigate to the Splunk Search page.
- In the Search bar, type the default macro
`audit_searchlocal(error)`
. - 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. - (Optional) Copy a fragment of the search.
- (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
- Select Settings > Advanced Search > Search Macros.
- Click New Search Macro to create a new search macro.
- For Name, enter newrate(2). The (2) indicates that the macro contains two arguments.
- For Definiton, enter the following:
This definition includes the argument variableseval new_rate=$val$*$rate$
val
andrate
. - For the Arguments field, enter val and rate.
- Enter a Validation expression that verifies that the value supplied for rate is numeric, as follows:
isnum($rate$)
- Enter the following Validation error message: "The rate value that you provided is not numeric. Enter a numeric rate value."
- 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))`
Define search macros in Settings | Dataset types and usage |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release), 9.2.2406
Feedback submitted, thanks!