Splunk macros

A Splunk macro can be thought of as a (hopefully, previously tested and otherwise validated) reusable assembly of Splunk (or business) logic—basically, any part or even all of a Splunk search that you don't want to type in again. Saved macros can even be defined to receive arguments when reused. Splunk macros are an integral part of knowledge management.

To understand how macros might be defined, saved, and reused, let's take a look at the previous example using the previously defined eval statement. In the following search, we defined a new field to be evaluated and searched on, named event_date:

sourcetype=TM1* error | EVAL event_date =  date_month  + "/" + date_mday + "/" + date_year | where event_date = "october/24/2007"

The event_date field is made up of the date_month, date_mday, and date_year fields. Since we will perhaps want to perform multiple searches in the future, searching for events that occurred on different dates and we don't want to retype the eval statement, we can save our definition of event_date as a macro, which we can call in our future search pipelines.

Creating your own macro

The easiest way to create a Splunk search macro is through Splunk Web. Under Settings, select Advanced Search and then click on Search macros.

In the Search macros page, you will see previously defined macros. You can then click on New to define the new search macro on the Add new page.

In the Add new page, you'll see the following fields:

• Destination app: This is the name of the Splunk app you want to restrict your search macro to; by default, your search macros are restricted to the search app.
• Name: This is the name of your search macro (in our example, we'll use TM1_Event_Date). If you want your search macro to take an argument, you will need to indicate this by appending the number of arguments to the name; for example, if TM1_Event_Date requires two arguments, it should be named TM1_Event_Date(2).
• Definition: This is the string that your search macro expands to when referenced in another search. If your search macro requires the user to type arguments, you will indicate this by wrapping dollar signs around the arguments; for example, $arg1$. The arguments' values are then specified when the search macro is invoked.

For your example, you can type the following eval statement to define your new search field into the Definition area in the Add new page:

EVAL event_date =  date_month  + "/" + date_mday + "/" + date_year

Using your macros

To include a saved Splunk search macro in a search, you need to use the left quote (also known as a grave accent) character. Note that this is not the straight quote character that appears on the same key as the double quote (").

Consider the following example:

sourcetype=TM1* error | `TM1_Event_Date` | where event_date = "october/24/2007"

In this example, I created a macro to avoid redefining my search field, event_date. What if I build on this idea—the idea is that if I regularly search for (in this case) TM1 error events that occurred on a specific date (that is, month/day/year), then why not just save the entire search as a Splunk macro that receives a date at search time? To do this, I can create a new macro, named TM1Events(1). Remember that the naming convention that Splunk understands is to include (in parentheses) the number of arguments that will be supplied at search time; so, in this case it will be 1. The following screenshot shows my macro definition (notice that I added my argument wrapped in dollar signs, $argme$) to the Definition area and named by a single argument (argme) in the Arguments area:

My macro definition

Now, we can use the following to run the Splunk search (to call my macro):

`TM1Events("october/24/2007")`

The limitations of Splunk

There really isn't any limit to the number of macros you can define or to the number that can be included in a single search; just keep in mind that when you read the preceding Splunk search example, one doesn't inherently know how TM1_Event_Date is defined. This is another area where a robust knowledge management strategy is critical.