A Lesson on Macros in Splunk (Part Two)

Let’s talk about macros (again).  Macros in Splunk are built into a lot of apps found on Splunk Base and heavily used in the Monitoring Console.  In part one, we talked through all the prep work and foundation Splunk macros. Now in part two, let’s jump into some methods to create macros, and talk a little about context and sharing. Let’s get cooking!


Making Macros

Let’s go ahead and make some macros.   We’ll create a few macros through the web interface, then I’ll take you behind the scenes to see what actually happens in the conf files.

In my lab, I’m going to switch to the Search & Reporting app and add a macro for a search I personally run quite often.  As I’m experimenting and developing in the lab, I always run this search when I get unexpected behavior as a starting point for root cause analysis.


index=_internal AND earliest=-5m AND (log_level=WARN* OR log_level=ERROR) AND sourcetype=splunkd


But, it’s kind of long and I get lazy so I’m going to set it as a short macro.  So now that we’re in the Search & Reporting app, I’m going to go back to Settings > Advanced Search and click on the “+ Add new” button on the Search macros line.

Figure 1 - Add new Splunk macro
Figure 1 – Add new Splunk macro

The destination app is already set correctly.  I’ll name the macro “myissues” – that should be a unique name that’s descriptive of its purpose.  In the Definition field, I’ll paste in my search from above.  We’ll keep it simple for now and not use another of the options to include arguments.  Click Save.

Now we’ll go back to the Search & Reporting app and use our macro to run a search.  Enter `myissues` (remember the backticks) and click the search button.

Figure 2 - Use macro to run a search in Splunk
Figure 2 – Use macro to run a search in Splunk

There you have it!  A short macro name in the search bar and I have my results.  And with way less typing that, to be honest, usually includes a typo or two.


Add Parameters to Your Macro

It’s kind of inflexible.  What if the issue isn’t caught in Splunk?  What if it occurred more than 15 minutes ago?  Or less than 15 minutes ago in a large environment so I want to restrict the time and speed up results?  Sure, you can use the time picker, but where’s the macro fun in that?  Let’s add some parameters to our macro to make it more useful.

Going back to the Advanced Search settings, I’m going t0 click the Clone button to create a copy of my macro, then edit that clone.  This time, I’m going to give my search a unique name and add “(2)” to the end of the name, indicating that it will expect two arguments.  Then, in the Definition field, I’m going to tokenize the search so Splunk knows where to place the arguments in the search.  In the Arguments field, I’m going to list my arguments, separated by commas.

Now, I’m going to add a little validation to this macro.  The timeframe submitted should be a number here.  Any text would cause the search to fail, so before running the search we’ll validate that field is in fact numbers.  In the Validation Expression box, I’m going to put a simple eval statement that should return TRUE if the input is correct.  If that validation fails, I can write a custom error message to show when the macro runs.  Once set, click Save.

Figure 3 - Add validation to your macro in Splunk
Figure 3 – Add validation to your macro in Splunk

Now we’ll go back to the Search app and test it.  I’ll search the following, to find web errors in the last 30 minutes: `myissues2(30,splunk_web_service)`

And we get results!

Figure 4 - Splunk validation of macro results
Figure 4 – Splunk validation of macro results

And a look at the Job Inspector shows the search expanded with the tokens replaced by my parameters.

Figure 5 - Review job inspector
Figure 5 – Review job inspector

And if I use something other than numbers for my $earliest$ token, I get an error with the message we just set.

Figure 5 - Watch out for this error in Splunk
Figure 6 – Watch out for this error in Splunk


New call-to-action


Storing Macros in Splunk

Great!  Now, if you’re a fan of the command line and get tired of GUI’s, let’s look behind the scenes.  If you’re not interested in how Splunk actually stores macros, then jump ahead.

OK, we know that most of Splunk’s knowledge objects and settings are stored in .conf files, and so it’s no surprise that macros are in a file called macros.conf.  Macros are user-level knowledge objects, at least when you create them in the web interface.  Since I was logged in as admin and working in the Search & Reporting app, I’ll navigate to /opt/splunk/etc/users/admin/search/local to find my personal configs for that app.

cat’ing the macros.conf file, we’ll see both of my macros in their own stanzas.  The settings we provided are now in alphabetical order rather than how we saw them on the web interface, but it should look familiar.

Figure 6 - Find your personal configs for the app
Figure 7 – Find your personal configs for the app


Permissions and Contexts

As mentioned briefly above, macros are privately owned by default – they’re only available to the user that created them and only in that app.  In the image below, I’ve logged in as a regular user and tried to run the admin macro created above.

Figure 7 - Error running macro in Splunk
Figure 8 – Error running macros in Splunk

The error is actually really descriptive.  We’ll follow instructions and go share this macro as the admin user.

Now, even though this particular macro is more admin oriented and not really useful to most users, I still want to be able to access it across apps.  That way I can troubleshoot from anywhere.  So it’s back to the Search Macros page under Settings > Advanced Search.  Filter for my macros and click the Permissions button.

Figure 8 - Filter for your macros in Splunk
Figure 9 – Filter for your macros in Splunk

To make sure I can use this macro in any app context, I’m going to select “All apps” under the “Object should appear in” section.  I’ll go ahead and leave the Permissions the same here because a regular user won’t have the right to read the _internal index anyways.  But that gets into another discussion of user roles and permissions that’s best left for another post.

Just to check that I can access my macro from anywhere, I’ll switch to another app and try accessing it again.  (Don’t mind the blanked out names, this is experimental and not ready for release….yet).

Figure 9 - Test your macros from anywhere
Figure 10 – Access your macro from anywhere

If you still have a terminal open where you just cat’ed macros.conf, hit the up arrow and enter.  You can see that the macro we just shared globally is gone.  It’s been moved to the search app, in the macros.conf in the local directory.  It hasn’t changed at all, but it did find a new home.

Figure 9 - Find your macros with open terminal
Figure 11 – Find your macros with an open terminal

One other advanced tip, if you want to see all the macros available to a given user, you can use a simple rest search:


| rest /servicesNS/-/-/admin/macros


This may be more information than you need to see but could help with some admin down the line, so I thought I’d share it.

Good luck with your Splunking!


Until Next Time…

Hopefully, this helps your understanding of macros: what they are, how to create and use them, and how to share them with other apps and users.  I’d love to give you a list of custom macros that everybody should have, but every Splunk customer and the user has different needs and different environments.

New call-to-action