Add comments to searches

You can add inline comments to the search string of a saved search by enclosing the comments in backtick characters ( ``` ).

Use inline comments to:

  • Explain each "step" of a complicated search that is shared with other users.
  • Discuss ways of improving a search with other users.
  • Leave notes for yourself in unshared searches that are works in progress.
  • Troubleshoot searches by running them with chunks of SPL "commented out".

Here is an example of a search with comments: 

sourcetype=access_* status=200 ```Get all successful website access events.```
| stats count AS views count(eval(action="addtocart")) AS addtocart count(eval(action="purchase")) AS purchases by productName ```Create counts of site views, add-to-cart actions, and purchase actions. Break them out by product name. ```
| eval cartToPurchases=(purchases/views)*100 ```Find the ratio of site views to purchases.```
|eval cartToPurchases=(purchases/addtocart)*100 ```Find the ratio of add-to-cart actions to purchases.```
| table productName views addtocart purchases viewsToPurchases cartToPurchases ```Put all this data into a table.```
| rename productName AS "Product Name", views AS "Views", addtocart AS "Add To Cart", purchases AS "Purchases" ``` Rename some table columns.```

In the Search Bar, the comments for this search are color-coded to make the comments easier to find:

An example of a complex search formatted into separate pipe sections, with comment text added to explain each "step" of the search.

The search processor replaces comments with a space when the search is run. For example, this comment ...| stats```Let's use 'stats' to count this```count becomes ...| stats count, when run not ... | statscount.

Comments and special characters

  • SPL comments support Unicode characters.
  • Comments ignore the backslash escape character. For example: \```This is still a comment. It is not escaped.```
  • Single and double backticks within a comment are considered to be part of the comment. For example: ```This comment has an extra backtick at the end. It's a valid comment. ` ```

Comment limitations

The following table describes limitations associated with using comments:

Comment limitation Example
A comment inserted before a generating command causes the search to fail. Common generating commands are tstats, makeresults, and gentimes. ```This search returns an error``` | tstats count WHERE host=x BY source
You can't insert comments inside a quoted string. "```The search processor treats this as an SPL string, not a comment.```"

Use comments to troubleshoot a search

You can use the inline comments to troubleshoot a search. Start from the end of the search and comment out the syntax of the last command. Work sequentially, from the end of the search syntax, commenting out each command syntax one at a time until you have Identified the problem.

The following search is attempting to return the bytes for each individual indexes. However, the search has the wrong field name in the stats command <split-by clause>. The name of the field is not index and an error is returned when this search is run. 

index=_internal source=*license* type=usage | stats sum(bytes) BY index

In this example, to identify the correct name of the field the stats command portion of the search is commented out: 

index=_internal source=*license* type=usage ```| stats sum(b) BY index```

When the search is run, the results show the correct name for the field, which is idx and not index.

Here is the revised search with the comments removed and the correct field in the stats command: 

index=_internal source=*license* type=usage | stats sum(b) BY idx

(Thanks to Splunk user Runals for this example.)

Keyboard shortcuts to add or remove comments

You can use the following keyboard shortcuts to add or remove comment characters in a search.

  • On Linux or Windows use Ctrl + /
  • On Mac OSX use Command + /

Add a new comment

To insert an empty set of comment characters at a specific place in your search:

  1. Position the cursor where you want the characters to appear and use the keyboard shortcut.
  2. You can then type your comment inside the comment characters.

Comment out part of a search

To comment out a specific part of your search:

  1. Highlight the part that you want to comment out.
  2. Use the keyboard shortcut to surround the highlighted lines with the comment characters.

Remove comment characters from part of a search

If you have commented out part of your search, you can restore that part of the search by removing the comment characters.

  1. Highlight the part of your search you want to restore.
  2. Use the keyboard shortcut to remove the comment characters from the highlighted lines in your search.