
Add comments to a search
The most flexible way to add comments to your search strings is to use the built-in comment macro. You can use the macro multiple times in your search string and multiple times in a single command string. Comments in a search do not impact search performance.
By default the comment macro is shared only in the Search app.
Using the comment macro
You can use the comment macro to add comments anywhere in your search string.
The syntax for a comment is `comment("comment text")`
.
Examples
`comment("THIS IS A COMMENT")`
`comment("This part of the search returns only one value")`
Comments begin and end with the back quote, or grave accent, character.
Adding multiple comments to a search
The following search example classifies recent earthquakes based on their depth.
source=usgs | eval Description=case(depth<=70, "Shallow", depth>70 AND depth<=300, "Mid", depth>300, "Deep") | stats count min(mag) max(mag) BY Description
When you add inline comments the search is easier to understand. This is the same search with multiple comments added to explain each part of the search.
source=usgs `comment("source is the us geological service (usgs)")` | eval Description=case(depth<=70, "Shallow", depth>70 AND depth<=300, "Mid", depth>300, "Deep") `comment("Creates field Description. Case function specifies earthquake depths, returns Description values - Shallow, Mid, Deep.")` | stats count min(mag) max(mag) `comment("Counts earthquakes, displays min and max magnitudes")` BY Description
Consider using uppercase characters for your comments to make them easier to find. This is the same search with the comments in uppercase.
source=usgs `comment("SOURCE IS THE US GEOLOGICAL SERVICE (USGS)")` | eval Description=case(depth<=70, "Shallow", depth>70 AND depth<=300, "Mid", depth>300, "Deep") `comment("CREATES FIELD DESCRIPTION. CASE FUNCTION SPECIFIES EARTHQUAKE DEPTHS, RETURNS DESCRIPTION VALUES - SHALLOW, MID, DEEP.")` | stats count min(mag) max(mag) `comment("COUNTS EARTHQUAKES, DISPLAYS MIN AND MAX MAGNITUDES")` BY Description
Using comments to troubleshoot a search
The following search example is attempting to return the bytes for the individual indexes. However, the search has the wrong field in the stats
command <split-by clause>.
index=_internal source=*license* type=usage | stats sum(b) BY index
You can comment out portions of your search to help identify problems. Another option is to run the search in Verbose mode. In this search the stats
portion of the search is commented out.
index=_internal source=*license* type=usage `comment("| stats sum(b) BY index")`
The results show the correct name for the field. You need to specify idx as the field name instead of index.
index=_internal source=*license* type=usage | stats sum(b) BY idx
(Thanks to Splunk user Runals for this example.)
PREVIOUS What's in this section? |
NEXT Calculate sizes of dynamic fields |
This documentation applies to the following versions of Splunk® Enterprise: 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 8.0.0
Comments
Is there a missing portion of this documentation in regards to what to do to enable these built-in comments? I'm running Splunk 7 and I don't see the search recognizing comment as a macro:
Error in 'SearchParser': The search specifies a macro 'comment' that cannot be found
Hello Jbillings
When you run the search, the search string is preprocessed to fill in tokens before the search is processed and the comment is ignored. You will need to remove the $s. Perhaps you can replace with something like this `comment("index=xyz sourcetype=dfg src=<addtoken>src</addtoken>")`
When using the comment macro, I have noticed that it won't work when the section being commented contains inputs in a panel. `comment("index=xyz sourcetype=dfg src=$src$")` will give an error since it will still try an populate the $src$ from the input.
If # doesn't mean anything, it would be super useful to be able to use that to comment whole lines or remainders of a line, like in python. Or // , or /*, or multiline string, or...
@Bcronrath if you are using it on an app other than search, you will have to change the sharing of the macro in "Settings > Advance search > Search macros" permission to Global.