Skip to content

A Lesson on Macros in Splunk (Part One)

Let’s talk about macros.  Not the scripts in MS Office often used to execute malicious code, but the little commands that can do big things in Splunk.  There’s a good chance you’re already using macros – they’re built into a lot of apps found on Splunk Base and heavily used in the Monitoring Console as we’ll see later.  In part one, I want to provide a little primer on what a macro is, show some examples of using macros. In part two, I’ll demonstrate methods to create macros, and talk a little about context and sharing.


What Are Macros?

In Splunk terms, macros are Knowledge Objects.  The Splexicon defines a search macro as “A knowledge object …  that contains a portion of a search or a search function”, and a Knowledge Object as “A user-defined entity that enriches the existing data in Splunk Enterprise.”

Put another way, a macro is a short command that can be used to replace parts of or all of search strings to make your SPL searches shorter and easier to understand.  Maybe this is to search multiple indexes without having to enter “index=a OR index=b OR index=r…” every time.  Or maybe it’s a way to ensure consistency by defining the span used on timecharts.

Macros are more powerful than just being a substitute for part of search.  You can also define parameters on a macro, allowing you to call the macro and pass in other fields or values.  This gives you the flexibility to, for instance, to calculate current sales in different currencies by setting the exchange rate as a parameter that you enter when running the search.  Or filtering to different office locations in the BY field of a stats command.


Let’s look at some examples…

All right, now that we’ve briefly acquainted you with macros as a concept, let’s look at some examples.  I like to use examples that Splunk users can access right now, without having to download a specific app or dataset, so we’re going to look at the Monitoring Console for most of our examples.  If you’re a User or Power User Role, you may not have access to the Monitoring Console.  But don’t worry, I’ll use plenty of images so you can see what’s going on and show some other examples you may be able to access as well.

Note: I’m running a simple set up of a single indexer and a single search head, running on docker on my laptop.  I’m a huge fan of the Splunk-Ansible project as a tool for Splunk users and developers to experiment with admin rights and no risk to an operational environment.

In the MC, I’m going to click on the Search pulldown, then Scheduler Activity and select Scheduler Activity: Deployment.

Figure 1 - Using scheduler activity: deployment for Splunk macros
Figure 1 – Using scheduler activity: deployment for Splunk macros

Find the Skip Ratio Across All Instances panel.  Should be second from the bottom on the right side.  Mouse over that panel and click the Open in Search button on the bottom right.

Figure 2 - Finding skip ratio for Splunk macros example
Figure 2 – Finding skip ratio for Splunk macros example

That should open a new tab with the search that populates the Skip Ratio panel.  The search you see should look like this:

Figure 3 - search results for skip ratio panel
Figure 3 – search results for skip ratio panel

There are two macros you’ll see here and they’re pretty easy to pick out.  Each macro, when called in an SPL search string, has to have a backtick at the beginning and the end.  Do note that’s not the same as a single quote; this key is usually found at the top left of your keyboard, surrounded by the ESC, Tab, and numeral one (1) keys.  So, the first is on line 1 and the second on line 3, `dmc_set_index_internal` and `dmc_timechart` respectively.

New call-to-action


But what’s it actually doing?  To see that, I’m going to click on Settings > Advanced Search, then choose Search Macros on the page.

Figure 4 - check out your search macros in advanced search
Figure 4 – Check out your search macros in advanced search

While writing this, my page loads with the Monitoring Console already chosen as the app filter, but you may need to manually set that.  Just looking at the summary here, we can see 128 macros owned by the Monitoring Console app (apparently, Splunk Inc. is a fan of search macros).

Searching for the first macro set above, we can see this is simply setting the search to start with “index=_internal”.  A very simple macro, I know.  But if you filter by the macro name, you’ll see that it’s used in 10 other macros (yes, you can embed one or more macros in another macro).  Let’s suppose, just for a moment, that Splunk decides to change that index from “_internal” to “_internals_” for some unknown reason in the future.  Changing the definition of this one macro to “index=_internals_” would then update the other 10 macros and the slew of panels that use them.  It’s a simple macro that substitutes a small part of a search but can make updating lots of searches and dashboards really simple.  Pretty neat.

Figure 5 - Setting the search to start with “index=_internal”
Figure 5 – Setting the search to start with “index=_internal”

Now we’ll look at the second macro found above.  `dmc_timechart` is a little different than our last example.

Figure 6 - Setting the search to start with “index=_internal” results
Figure 6 – Setting the search to start with “index=_internal” results

It’s another simple macro but used here to set the minspan option of the timechart.  As I mentioned previously, this provides a way to have consistency across different panels and searches without having to explicitly set the option in each.  And, as simple as it, it appears this macro is used 27 different times[i] in the MC itself.  As before, changing this one macro can do a lot.

Now that we’re looking at the macros themselves, scroll until you find the macro called `dmc_tcp_throughput_split_by(2)`.  You’ll notice right away this one is a little different, ending with a number in parenthesis.  This is an implementation of the parameters that I mentioned above.  The number 2 indicates that the macro expects two parameters, and the Arguments column shows that those are “field” and “group”.  You can also see the tokens “$field$” and “$group$” in the definition.

Figure 7 - `dmc_timechart` macro results
Figure 7 – `dmc_timechart` macro results

So, if you were to use this macro manually, it would look something like this:

`dmc_tcp_throughput_split_by(<field to replace $field$ token>, <group to replace $group$ token)`.

Until Next Time…

That wraps up the first part of the Splunk macros breakdown. I hope you could take back some tips from understanding and exploring some macros examples. The real juicy content will be coming shortly in Part Two, where I’ll show you how to make macros in Splunk. Stay tuned for the next part, as well as upcoming blogs. Until then, shoot us your information below if you’ve got any guidance on using Splunk or want to connect on topics like this.

New call-to-action