Splunk® Enterprise

Search Manual

Acrobat logo Download manual as PDF

Acrobat logo Download topic as PDF

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=accesss_* 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.

SPL commenting rules

You insert a comment into a search string by placing three backtick characters ( ``` ) before and after your comment text. Commented text is parsed by the search processor as a blank space.

Here's the full set of SPL comment rules:

SPL comment rule 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 insert comments anywhere in a line of SPL, except inside a quoted string. "```The search processor treats this as an SPL string, not a comment.```"
Comments ignore the backslash escape character. \```This is still a comment. It is not escaped.```
The search processor replaces comments with a space when the search is run. ...| stats```Let's use 'stats' to count this.```count

This becomes ...| stats count, not ... | statscount

Comments that do not start and end with a triple backtick cause a fatal syntax error. Single and double backticks within a comment are considered to be part of the comment. ```This comment has an extra backtick at the end. It's a valid comment. ` ```

SPL comments support Unicode characters.

Use comments to troubleshoot a search

You can use the inline 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. In this search, the stats portion of the search is commented out.

index=_internal source=*license* type=usage ```| 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.

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.)

Last modified on 02 June, 2021
Help reading searches
Search actions

This documentation applies to the following versions of Splunk® Enterprise: 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 9.0.0

Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters