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:
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.)
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.1.11, 8.1.12, 8.1.13, 8.1.14, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 9.0.4, 9.0.5, 9.0.6, 9.0.7, 9.0.8, 9.0.9, 9.0.10, 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.1.4, 9.1.5, 9.1.6, 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.3.0, 9.3.1
Feedback submitted, thanks!