Search macro examples
Here are some search macro use cases and their solutions.
- Learn how to use your search macros in search strings .
- Learn how to create or update search macros in Settings.
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.
- Create a search macro named
iis_search(1)with this definition:
sourcetype="iis" cs_username!="-" /$fragment$/ .pdf
- In the Arguments field, provide fragment as the argument.
- 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.
- Learn how to insert search macros into search strings.
- Understand how to design a search macro definition.
- Navigate to the Splunk Search page.
- In the Search bar, type the default macro
- 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.
- (Optional) Copy a fragment of the search.
- (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
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
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.
- Navigate to Settings > Advanced Search > Search Macros and click New to create a new search macro.
- Give the search macro the following Name: newrate(2). This name indicates that the macro contains two arguments.
- Give the
newrate(2)search macro the following Definiton:
This definition includes the argument variables "val" and "rate".
- For the Argument field, list val and rate.
- 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:
- Provide the following Validation error message: The rate value that you have provided is not numeric. Enter a numeric value.
- Save your search macro definition.
When you use the
newrate(2) macro in a search, you might fill out the arguments like this:
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
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