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:

[comment(1)] 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:

index=_internal `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!