Page tree
Skip to end of metadata
Go to start of metadata

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 Getting started with search. 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:

  1. 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
  2. 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:

What do I want to do?Search commandDescription

Manipulate search results by performing the following functions:

  • Group
  • Order
  • Filter
fieldsKeep or remove fields in search results.
filterFilter results based on a criteria condition.
topGet the most common values of a field.
rareGet the least common values of a field.
head

Return the first n search results based on sort order. The head command returns the last n entries for descending results.

tail

Return the last n search results. The tail command returns the first n entries for descending results.

dedupRemove data records that contain fields with duplicate values.

Perform first-level analysis such as the following:

  • Simple pattern matching
  • Comparison
  • Basic statistics
chgnameChange the name of a field.
chgvalueArrange values into buckets based on user-defined ranges.
concatConcatenate field values (or string values) and assign them to the specified target field
difftimeCompute the difference between the current time stamp and the event time stamp and assign the value to a new "difftime" field.
evalEvaluate 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.
extractExtract field values or raw event data and assign the values or data to new fields by using the Java regular expression capturing groups.
extractkvExtract name=value pairs from raw event data depending on the delimiters specified.
statsCreate an aggregate representation of data in the form of a table of statistics and a corresponding chart based on the fields specified.
tableExtract fields from events with information in a tabular format.
valmapClassify numeric field values with a specified category name depending on the range specified.
Present (or report) data quickly by specifying a search stringtimechartCreate 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 complex pattern matching

groupGroup events depending on the group options (conditions) specified to create a transaction of events.

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:

  • Tabular View: Displays search results in a table.
  • Compare Data: Provides compare options that you can use to compare charts across a different time context, different search query, or both.

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

The following table provides information about the various views available.

Kind of viewDescription 
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 typeClick 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 from the three dots menu next to the time range displayed and click Compare to see a comparison of charts. You can also specify a new search query in the box displayed under the time range and then click Compare. This helps you understand how your current search results differ from the compared time context.

Note: If the original query contains a long string separated by pipes (|), then the comparison run (against the next query) is only based on the portion of the original query before the first pipe.

After you run a comparison, you can return to the compare options; to do this, click Expand to change options at the bottom-right of the chart and change the search query or select another compare option. After selecting the compare option, or changing the search query, or both, you need to click Change to run the comparison.

Compare option

Example

Same time

Compares the current chart with another chart for the same time context, but a different search query. You need to provide the new search query to enable the comparison

Not applicable

Previous time (same duration)

Compares current chart with the chart for
before the original time context.

Original: Feb 26, 11:51am - Feb 26, 12:51pm

Compared: Feb 26, 10:51am - Feb 26, 11:51am

Previous day (same duration)

Compares current chart with the chart for
the time context that is one day prior to the
original time context.

Original: Feb 26,11:51am - Feb 26, 12:51pm

Compared: Feb 25,11:51am - Feb 25, 12:51pm

Previous week (same duration)

Compare current chart with the chart for
the time context that is one week prior to the
original time context.

Original: Feb 26, 11:51am - Feb 26, 12:51pm

Compared: Feb 19, 11:51am - Feb 19, 12:51pm

Best practices for chaining multiple search commands

When you are building a complex search command by chaining multiple search commands (for example, error | filter greaterthan(price,"10") | timechart span=1d count(HOST)), follow these recommendations. This is necessary because the time slicing happens after all the search results are processed. This hampers the Search component capabilities and the results appear slowly.

  • Narrow down on specific time (for example, last 6 hours, 24 hours, 2 days rather than 15 days period) and then construct a multilevel search command (or multiple search commands chained together) to enable faster product performance. Certain search commands such as filter and group process each entry in the search results. Therefore reducing the time duration helps in getting faster results for these commands.
  • When constructing multilevel search commands, build the search incrementally, and validate one level at a time.
  • After you have validated the results of a search command and you are satisfied with it, save the query to create a saved search. Saving a search ensure that the same search query can be reused and leveraged by others.

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.
  • By default, field names and tag names are case sensitive. While searching, you cannot control case sensitivity for field names and tag names. However, you can control case sensitivity for field values and tag values. For more information, see Case-sensitive search and case-insensitive search.
  • Search commands that rely on fields work only if the specified field is present in the search results.

  • Search command names and their associated functions and operators are case-insensitive. For more information, see Case-sensitive search and case-insensitive search.

    Examples

    • Searching for Response Size in the raw data is the same as response size.
    • Searching for ... | group maxevents=2 maxspan=2m is the same as ... | Group MaxEvents=2 MaxSpan=2m