The Official Way To Comment Splunk SPL

Over the years, I’ve written some crazy long searches in Splunk. When searches get to 30-40 lines, its a really good idea to comment it, so that when it comes time to troubleshoot it or amend it later, the comments make it easy to debug and decode.

Unfortunately, there is no specific comment function in Splunk to help you annotate your code.

I’ve played around with a few things over the years, including creating a comments field using eval:

| eval comment=”This is a comment.”

However, the above “eval solution” is not efficient because a “comment” field is created for each result. This overhead grows as the number of events increase. So what to do? Well, I generally write comments in accompanying documentation, especially when delivering Splunk solutions to clients. Not ideal, because it is easy for the search itself and the documentation to get out of sync, but it was the best I could come up with. At least I had something which documented my line of thinking.

Imagine my delight, when Splunk’s excellent Smart AnSwerS blog pointed out that Splunk’s Search Manual has been recently updated to reflect a recommended way to add comments to Splunk searches. How? Through the use of a macro. A macro is a knowledge object that contains a portion of a search or search function. It promotes re-use of search logic in a repeatable, efficient manner.

In order to add a comment using the macro method, you use something similar  the following:

`comment(“comment text”)`

Don’t forget that in order for the above comment macro work, place the following into macros.conf:

args = text
definition = “”
iseval = 1

The great thing is with macros is that you can use it any number of times in a search. Here is an example:

`comment(“This is the base search to get all Splunk internal events”)`
| stats count
`comment(“We are doing a count of events”)`

The best thing about the macros approach is that it has no performance or resource impact!

Is it a hack? Yes! Does it allow me to finally annotate my Splunk searches without resource impact? Hell, yes!





  • LauraS

    Hey Shaun, thanks for adding this to the blog! Splunk users have tried various ways to add comments to Splunk SPL over the years, like your Eval hack. According to Steve Zhang (Splunk SPL guru) only a macro has no impact on performance. I worked with Steve to document the macro method and add it to the Spunk Search Manual. Glad you found it there and shared it on your blog!
    LauraS, Senior Tech Writer at Splunk

  • ppablo

    Glad you found the solution valuable and thanks for the Smart AnSwerS blog shoutout! 🙂

    Community Content Manager, Splunk

Add your comments

Your email address will not be published. Required fields are marked *