Splunk Cloud Platform

Search Manual

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.

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 03 January, 2024
Help reading searches   Search actions

This documentation applies to the following versions of Splunk Cloud Platform: 9.2.2403, 8.2.2202, 8.2.2203, 8.2.2112, 8.2.2201, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308 (latest FedRAMP release), 9.1.2312

Was this topic useful?

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