Using comments in SPL2

You can add comments to your SPL2 search string to explain a portion of a search, or to use as a troubleshooting technique. SPL2 supports both block comments and line comments.

  • Block comments use this tagging: /* ... */
  • Line comments use this tagging: //

Block comments

SPL2 block comments begin with a leading forward slash followed by an asterisk and end with a trailing asterisk and forward slash.

For example, suppose you have the following search: 

... | eval bytes = k * 1024 | stats sum(bytes) by host

You want to add a comment that explains what the k field contains. 

... | eval bytes = k * 1024 /* k contains kbytes */ | stats sum(bytes) BY host

Here's another example.

The following search classifies recent earthquakes based on their depth: 

| FROM index=mydataset WHERE 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 comments to a search, the search is easier to understand. This is the same search with multiple block comments added to explain each part of the search: 

| FROM index=mydataset WHERE source=usgs /* The source is the us geological service (usgs) */
| eval Description=case(depth<=70, "Shallow", depth>70 AND depth<=300, "Mid", 
depth>300, "Deep") /* Creates the field Description. Case function specifies earthquake depths. Returns Description values - Shallow, Mid, Deep. */
| stats count(), min(mag), max(mag) /* Counts earthquakes. Displays min and max magnitudes */ BY Description

Alternatively, you can use block comments at the start or end of a search string. For example: 

/* The source is the US geological service (USGS). 
Eval creates the field Description. 
Case function specifies the earthquake depths. Returns Description values - Shallow, Mid, Deep.
Stats counts earthquakes. Displays min and max magnitudes */
| FROM index=mydataset WHERE 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
Note: You cannot have block comments in any portion of your search that uses the search command.

Line comments

You can use line comments within any SPL2 command in your search pipeline. Line comments begin with a double forward slash ( // ) and end with a new line.

For example: 

... | eval bytes = k * 1024 // the k field contains kilobytes
| stats sum(bytes) by host

Keyboard shortcut for line comments

You can use a keyboard shortcut to add or remove line comments.

Select one or more rows in your module and apply the keyboard shortcut for your operating system:

Windows or *nix

Ctrl + /

MacOs

Command + /

Using comments to troubleshoot a search

The following search example is attempting to return a sum of the bytes for a specific range of IP addresses, organized by host names. However, the search has a misspelling for field name hosts in the stats command BY clause. 

| FROM main WHERE ipaddress LIKE "198.%" | stats sum(bytes) BY hosts

You can comment out portions of your search to help identify problems. In this search, the stats portion of the search is commented out: 

| FROM main WHERE ipaddress LIKE "198.%" // | stats sum(bytes) BY hosts

The results show that the correct name to use for the field is host and not hosts.

The following search shows the correct syntax: 

| FROM main WHERE ipaddress LIKE "198.%" | stats sum(bytes) BY host