Search commands

You can perform a search to troubleshoot issues by specifying a search criteria on the Search tab. Your search criteria (search string) can be composed of words, name=value pairs, fields, tags, and so on. For more information, see Searching-the-data. The search string is a set of expressions that are separated by various logical operators such as two ampersands (&&), two pipes (||), and so on. For more information, see Search string syntax.

This topic contains the following information:

What are search commands?

Search commands are a set of commands containing arguments and can be run on the output of a particular search that you must have already performed. You can chain a set of search commands so that the output of one search command is consumed as the input to the subsequent search command. Multiple search commands can be chained by using a pipe separator (|).

Some of the commands add fields that you can use for further processing your data. For example, when you run the group command, the following fields are automatically added in each of the records displayed:

duration
numentries
group_complete

For other commands such as extract or table, the additional field names are dynamic in nature and are added depending on the input specified. These fields can be used in subsequent commands added to your existing search query. These fields are virtual fields and cannot be added to the Fields section under the Filters panel.

Advantages of using search commands

At a high level, you can use search commands for the following purposes:

Performing advanced analysis on your existing search results; for example, simple or complex pattern matching
Simplifying your troubleshooting tasks
Breaking down your search results into smaller parts
Examining your search results from different viewpoints
Manipulating your search results by using functions such as filtering and grouping

Use cases

The following example use cases provide scenarios that help you better understand the value of using search commands.

Examples

Scenario 1

John has an application hosted on the cloud. The application web tier is hosted on an Apache HTTPD server, which provides information regarding all URLs accessed. This information is stored in the access.log file.

Goal: John wants to find out which browsers are most used by customers, to decide on the browsers for which support must be continued.

To find out the most used browsers, John needs to use a command that provides a total count of the URLs accessed using the various browsers. Suppose in the data that John is monitoring (access.log), there is a browser field; John can run the stats command with the count function on the browser field.

Action: Run the following search command on the log entries related to the access.log file:

COLLECTOR_NAME=access.log | stats count(browser) by browser

Scenario 2

John wants to create a traffic-light indicator for the cpupercent field (CPU usage) in the following manner and summarize the results in a chart:

If CPU usage is from 0 to 5%, mark it with the value GREEN.
If CPU usage is from 6 to 50%, mark it with the value YELLOW.
If CPU usage is above 50%, mark it with the value RED.

Actions:

Run the following search command to create a new range field with the value GREEN, YELLOW, or RED, depending on the value of the cpupercent field, and then change the range field to CPU_STATUS.
COLLECTOR_NAME="script_54" | valmap field=cpupercent GREEN=0-5 YELLOW=6-50 RED=51-100 | chgname range with CPU_STATUS
Append the search query in the previous step with the stats command to see the values summarized in a chart. The search query will look as follows:
COLLECTOR_NAME="script_54" | valmap field=cpupercent GREEN=0-5 YELLOW=6-50 RED=51-100 | chgname range with CPU_STATUS | stats count(HOST) by CPU_STATUS

Supported search commands

The following table provides a list of supported search commands for achieving various goals:

Tabular commands

Search commands that provide tabular output are considered as tabular commands, which include the following:

Tabular commands provide a time-series representation of data in the form of a table of statistics and a corresponding chart based on the field or fields specified.

When you run a tabular command, by default, the results are summarized in the chart view. To see the results summarized in various ways, click the vertical three dots menu next to Chart View and select one of the following options:

Show Tabular View: Displays search results in a table.
Show Compare View: Displays search results as a chart and provides compare options that you can use to compare charts across different time contexts.

To return to the chart view, select Show Chart View from the vertical three dots menu.

The following table provides information about the various views available.

Kind of view	Description
Chart View	Provides a graphical representation of data. Click this view and select one of the following options to view a graphical representation of the search results.
	Chart type	Click to preview
	(Default) Bar
	Column
	Line
	The bars displayed in the chart are clickable. When you click a value in the table, the tabular view is toggled to the search results view and events associated with those values are displayed. By default, the legend is displayed. To hide the legend, clear the selected Show Legend check box.
Tabular View	Provides a tabular representation of data. The values displayed in the table are clickable. When you click a value in the table, the tabular view is toggled to the search results view and events associated with those values are displayed.
Compare View	Select one of the following compare options and click Compare to see a comparison of charts; this helps you understand how your current search results differ from the compared time context. The original timeline chart is displayed with the notation C1 while the compared chart is displayed with the notation C2. To return to the compare options, click Compare Options. By default, the legend is hidden. To show legend, select the Show Legend check box.
	Compare option	Example
	(Default) Previous time context Compares current chart with the chart for before the original time context.	Excerpt named previous time original was not found in document xwiki:IT-Operations-Management.Operations-Management.BMC-TrueSight-IT-Data-Analytics.itda20.Using.Search-tab.Compare-results.WebHome. Excerpt named previous time compared was not found in document xwiki:IT-Operations-Management.Operations-Management.BMC-TrueSight-IT-Data-Analytics.itda20.Using.Search-tab.Compare-results.WebHome.
	Fixed time context, previous dayCompares current chart with the chart for the time context that is one day prior to the original time context.	Excerpt named previous day original was not found in document xwiki:IT-Operations-Management.Operations-Management.BMC-TrueSight-IT-Data-Analytics.itda20.Using.Search-tab.Compare-results.WebHome. Excerpt named previous day compared was not found in document xwiki:IT-Operations-Management.Operations-Management.BMC-TrueSight-IT-Data-Analytics.itda20.Using.Search-tab.Compare-results.WebHome.
	Fixed time context, previous weekCompare current chart with the chart for the time context that is one week prior to the original time context.	Excerpt named previous week original was not found in document xwiki:IT-Operations-Management.Operations-Management.BMC-TrueSight-IT-Data-Analytics.itda20.Using.Search-tab.Compare-results.WebHome. Excerpt named previous week compared was not found in document xwiki:IT-Operations-Management.Operations-Management.BMC-TrueSight-IT-Data-Analytics.itda20.Using.Search-tab.Compare-results.WebHome.
	Custom time Compare current chart with the chart for a custom time context. Note: By using this option, you can only edit the start time and not the end time. This is because the time difference used to compare the original time context and the custom time context needs to be the same.	Excerpt named custom time original was not found in document xwiki:IT-Operations-Management.Operations-Management.BMC-TrueSight-IT-Data-Analytics.itda20.Using.Search-tab.Compare-results.WebHome. Excerpt named custom time compared was not found in document xwiki:IT-Operations-Management.Operations-Management.BMC-TrueSight-IT-Data-Analytics.itda20.Using.Search-tab.Compare-results.WebHome.

Notes about using search commands

When you run a search command, if you specify a field name that does not exist, search results that do not contain the field name are not impacted.
If you use special characters such as double quotes (") and backslash (\) in your search syntax, you must use a backslash as an escaping character before the special character. For more information, see Escaping characters.

Field names are case sensitive.
Search commands that rely on fields work only if the specified field is present in the search results.