Commenting Search Code

[reed_kelly]

I would like to add comments to my searches, saved searches, macros and just about anywhere that I write search syntax. I have searches that have dozens of lines and they still call macros to organize the syntax and reduce duplication.

I thought of adding a bunch of evals:

...| eval comment="Added splunk_server check to reduce load on slow indexers..."

But this has side effects and causes a slight increase in resource consumption.

Does anyone have a more elegant way to comment search code?

[keiichilam]

some extra cost in execution:
index=_internal * |head 1 | COMMENT TEST| COMMENT TEST| COMMENT TEST| COMMENT TEST| COMMENT TEST

Duration (seconds) Component Invocations Input count Output count
0.23 command.COMMENT 5 5 5

But This is really nice!

[GregZillgitt · Accepted solution]

I created a do-nothing "comment.py" (and associated commands.conf stanza), dropped it into the search app's bin directory, and voila! Now I can do this:

... some commands | COMMENT This is a comment | ... more commands

Here's comment.py:

---

import splunk.Intersplunk

def docomment(results, settings):
    # do nothing
    splunk.Intersplunk.outputResults(results)

results, dummyresults, settings = splunk.Intersplunk.getOrganizedResults()
results = docomment(results, settings)

---

commands.conf:

---

[comment]
retainsevents = true
streaming = true
filename = comment.py

---

That's it!

Quick & dirty deploy: drop comment.py in $SPLUNK__HOME/etc/apps/search/bin, commands.conf in $SPLUNK_HOME/etc/apps/search/local, and restart.

Probably should be packaged in its own app using the new templated approach.

[steveyz]

Unfortunately, this approach means that the comment command ends up de-serializing and re-serializing every event from and to CSV in python. That's in general fairly costly.

A macro based approach would be best. Basically define a comment macro that evaluates to the empty string regardless of the input argument.

[lstewart_splunk]

And a macro method is documented here:
http://docs.splunk.com/Documentation/Splunk/latest/Search/Addcommentstosearches

[reed_kelly]

This is a great solution to the problem, so I gave it the check! I would still like to see a native solution from Splunk, however. For example, I might want to do something like the following to comment pieces of a SPL. (similar to C-style)

| timechart \/*limit=20*\/ limit=5 span=\/*5m*\/10m count by sourcetype

[snoobzilla]

Would this approach add noticeable overhead?

[reed_kelly]

I found another thread on this with useful suggestions:

http://splunk-base.splunk.com/answers/48865/add-a-comment-to-a-search

[reed_kelly]

It would also be nice to be able to comment out a section of a search without deleting the original text. This may come in handy for a quick fix.

I think I should file an enhancement request. I was just fishing for ideas in the mean time.

[reed_kelly]

Thanks. I want something that is a first-class citizen in the search command so that it is also passed to alert scripts and other Splunk things. It would also be nice to be able to copy and paste the entire search and know that you were grabbing the comments as well.

[sowings]

This isn't an answer per se, but I typically comment the search strings or macros within macros.conf itself, or perhaps the XML of a view / dashboard definition.