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.
Search commands are complex search strings available by default with the BMC TrueSight IT Data Analytics product. 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.
Note
These fields are virtual fields and cannot be added to the My Fields section on the Filter Pane.
This topic contains the following information:
At a high level, you can use search commands for the following purposes:
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)
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:
Actions:
COLLECTOR_NAME="script_54" | valmap field=cpupercent GREEN=0-5 YELLOW=6-50 RED=51-100 | chgname range with CPU_STATUS
The following table provides a list of supported search commands for achieving various goals:
Notes
Field names are case sensitive.
Search commands that rely on fields work only if the specified field is present in the search results.
What do I want to do? | Supported search command | Description |
---|---|---|
Manipulate search results by performing the following functions:
| fields | Keep or remove fields in search results. |
filter | Filter results based on a criteria condition. | |
top | Get the most common values of a field. | |
rare | Get the least common values of a field. | |
head | Return the first n search results based on sort order. The | |
tail | Return the last n search results. The | |
Perform first-level analysis such as the following:
| chgname | Change the name of a field. |
chgvalue | Arrange values into buckets based on user-defined ranges. | |
concat | Concatenate field values (or string values) and assign them to the specified target field | |
difftime | Compute the difference between the current time stamp and the event time stamp and assign the value to a new "difftime" field. | |
eval | Evaluate an expression (a field name along with a specified operation) and assign the resulting value to a new field; for example, change the case of a field value, split a field value, and copy portions of a field value. | |
extract | Extract field values or raw event data and assign the values or data to new fields by using the Java regular expression capturing groups. | |
extractkv | Extract name=value pairs from raw event data depending on the delimiters specified. | |
stats | Create an aggregate representation of data in the form of a table of statistics and a corresponding chart based on the fields specified. | |
table | Extract fields from events with information in a tabular format. | |
valmap | Classify numeric field values with a specified category name depending on the range specified. | |
Present (or report) data quickly by specifying a search string. | timechart | Create a time-series representation of data in the form of a table of statistics and a corresponding chart based on the fields specified. |
Perform advanced analysis such as the following:
| group | Group events depending on the group options (conditions) specified to create a transaction of events. |