Search command summary

This topic provides a summary of all search commands available with the product. You can use this information for reference purposes.

To save an offline copy of this page, download the Search command summary PDF.

chgname

This search command changes the name of one or more fields with new names that you specify. You can use this command to simplify your troubleshooting tasks by changing complex field names to meaningful names. By using this command, you can rename a given field or multiple fields. Multiple fields can be separated by using a comma (,) or a space.

Syntax

chgname <Source-Field> with <Target-Field>+

In the preceding syntax, the following definitions apply:

• + indicates one or more similar expressions separated by a comma (,) or space.
• <Source-Field> refers to the field that you want to rename.
• <Target-Field> refers to the new field name with which you want to replace the existing field name.
• "<Phrase>" refers to the phrase with which you want to replace the existing field name. You must enclose a phrase in double quotes (").

Examples

Example 1: Rename the COMPID field with ComponentID:

For more details, see the long example at chgname search command.

Back to top ↑

chgvalue

This search command replaces the value of a specified field (or field list) with new values. This command is useful when you have multiple fields with the same value and you want to change that value to a new value.

Syntax

chgvalue <Existing-String> with <New-String>

chgvalue <Existing-String> with <New-String> [in <Field-List>]+

In the preceding syntax, the following definitions apply:

• + indicates one or more similar expressions separated by a comma (,).
• [Expression] indicates it is optional.

• <Existing-String> refers to the existing value of the specified field or fields that you want to change.

• <New-String> refers to the new value with which you want to replace the existing value. If the new string is a phrase, enclose it in double quotes (").

• <Field-List> refers to a comma- or space-separated list of field names. If you do not specify a list of field names, by default the command replaces the value of all fields with the existing string.

Examples

Example 1: Replace a value with a new value in a single specified field:

Example 2: Replace a value with a new value in multiple specified fields:

Example 3: Replace multiple values of a field with more descriptive names in single specified fields:

Example 4: Replace multiple values of a field with more descriptive names in multiple specified fields:

Example 5: Replace multiple values with new values in all fields:

Example 6: Replace a phrase value with a new value in a single specified field:

For more details, see the long examples at chgvalue search command.

Back to top ↑

concat

This search command concatenates field values (or string values) and assigns the result to the target field that you specify. The string value can consist of a phrase containing non-alphanumeric characters (string literals) that you specify in double quotes ("), or a field name (source field) whose value must be used as the value of the target field. You can specify multiple fields separated by a space. You can also specify a combination of fields and phrases.

Syntax

concat <Source-Fields+> <Target-Field>

In the preceding syntax, the following definitions apply:

• + indicates one ore more similar expressions separated by a space.
• <Source-Fields> refer to a list of fields or a combination of fields and phrases (enclosed in double quotes) to use for concatenating.
• <target-Field> refers to the target field to which you want to assign the concatenated string of field values and specified phrases. This target field must always be defined after the list of source fields (or phrases).

Examples

Example 1: Create a target field, email address, that combines the value of the field username, the string "@" and value of the field host.

... | concat username "@" host "email address"

Example 2: Create a target field, address, that combines the HOST and port field values and the string ":" in the format <HOST>:<port>.

... | concat "Request of type" RequestType "from client" ClientIp "to server" HOST 
message

For more details, see the long example at concat search command.

Back to top ↑

dedup

This search command removes data records that contain fields with duplicate values.

Records are removed based on the field names specified. Depending on the field name, the first instance(s) of the record(s) is kept, while the rest of the records are removed. You can specify a number (N) as the count of records (with duplicate field values) to be kept. For example, you can keep the first three records with the same value and remove the remaining duplicate records.

You can also see the number of duplicate records removed. This can be done by specifying the showDetails option. By doing this, the DuplicatesRemoved field is added to each record kept. The value of this field is a number that indicates the count of the records removed. Specifying the showDetails option is required for running the sortby and the multiple parameters.

If you want to sort the search results, then you can specify the sortby parameter based on a field. By default the sorting happens in a lexicographical order. If you want to sort the results based on a field with numeric values, then you also sort the results numerically.

If you want to further analyze your data to see values of another field in the removed records, then you can use the multiple parameter. This can help you see multiple values of the field for the records returned by the dedup command.

Syntax

dedup [N] [showDetails] <field>+ [sortby <sort-by-option>(<field>)] [multiple <field>]

In the preceding syntax, the following definitions apply:

• N indicates a number that represents the count of records with duplicate field values to be kept. By default, this number is 1.
• + indicates one or more similar expressions separated by a space
• [Expression] indicates it is optional.
• showDetails indicates whether you want to know the number of duplicate records removed for each unique field value. If you specify this option, the DuplicatesRemoved field is added to each record.
• <field> refers to field name on which you want to run this command or the field name on which you want to run the sortby or the multiple parameter.

• sortby indicates an optional parameter that you can run on a field name. You can add this parameter to sort the search results based on the value of the field specified. You can use one of the following options for sorting the search results:

  Option	Description
  num	Sorts the search results in a numerical order.
  str	Sorts the search results in a lexicographical order.

  Notes

  • Even if you do not specify the str option and only specify the field name, by default the search results are sorted in a lexicographical order.
  • This parameter can be used only when your command syntax uses the showDetails option.

• multiple <field> indicates an optional parameter that you run on a field name to see the unique values of that field occurring in the records returned by running this command.

  Note

  This parameter can be used only when your command syntax uses the showDetails option.

Example

Example 1: Remove duplicate search results with the same ClientIp field value.

... | dedup ClientIp

Example 2: Remove duplicate search results containing the same values, for both the ClientIp and ResponseCode fields.

... | dedup ClientIp ResponseCode

Example 3: Remove duplicate search results with the same RequestType field value. Additionally, see the number of duplicate records removed and see the unique values of the ResponseSize field in the duplicate records removed.

... | dedup showDetails RequestType multiple ResponseSize

Example 4: Remove duplicate search results with the same RequestType field value. Additionally, see the number of duplicate records removed and sort the search results by the ResponseSize field in an ascending order.

... | dedup showDetails RequestType sortby num(ResponseSize)

For more details, see the long example at dedup search command.

Back to top ↑

difftime

This search command computes the difference between the current time stamp and the event time stamp and assigns the value to a new field called "difftime". This new field is a virtual field that provides an easy-to-read value such as "1 day ago," "2 minutes ago," "4 seconds ahead," and so on.

Syntax

difftime

Example

Example 1: Create a new difftime field that provides the difference between the current time stamp and the event time stamp.

For more details, see the long example at difftime search command.

Back to top ↑

eval

This search command evaluates an expression (a field name along with a specified function) and assigns the resulting value to a new field that you specify. When you specify a field, the product runs specified functions on the value of that field and then assigns the resulting value to a new field so that you can further analyze it.

You can perform the following functions:

• Changing the case of a field value to lowercase or uppercase
• Splitting the value of a field into multiple parts depending on the delimiters specified
• Copying portions of a field value

Delimiters can be alphanumeric characters, special characters, or Java regular expressions. When you run the split function, the resulting values are assigned to the new field. Because fields with multiple values are displayed as a comma-separated list, the resulting values from a split function are also displayed as a comma-separated list.

You can also use the split function with a copy function (mvindex) in the command syntax, so that one of the values received by running the split function is copied to the new field.

You can copy portions (a range of values) by specifying a starting index and ending index so that a range of values is copied from the source field and assigned to the new field. The value of the index indicates the particular portion of the field value that must be copied. For example, if the source field has a list of five values and you specify the starting index as 0 and the ending index as 3, then a range of values from the first to the fourth portions is copied and assigned to the new field.

Syntax

eval <New-Field>=<Expression>

In the preceding syntax, the following definitions apply:

• <New-Field> refers to the name of the new field to which you want to assign the value that was received as a result of running the specified function.

• <Expression> refers to a combination of the specified function and the name of the source field on which you want to run the function.

  The following table lists the functions supported:

  Function	Syntax	Description
  lower	lower(<Source-Field>)	Changes the case of the source field value to lowercase
  upper	upper(<Source-Field>)	Changes the case of the source field value to uppercase
  split	split(<Source-Field>, "<Delimiter>")	Splits the source field value depending on the delimiter specified. The delimiters can be alphanumeric characters, special characters or Java regular expressions and must always be enclosed in double quotes ("). Note: If you want to use special characters such as period (.) or asterisk (*) as a normal delimiter and not as a Java regular expression, you must use an escaping backslash character (\) before the special character.
  mvindex	mvindex(<Source-Field>, <Start-Index>[,<End-Index>]) where, [Expression] indicates it is optional	Copies portions of the source field value depending on the index specified. You can specify a starting index and an ending index so that a comma-separated range of values is copied from the source field and assigned to the new field. Specifying the ending index is optional. Index is a number starting from 0 to 9 (read from left to right) and -1 to -10 (read from right to left), indicating the portion of the field that must be copied. Zero indicates the first portion and -1 indicates the last portion. The end index must be greater than the start index.

Examples

Example 1: Create a new field, req_type_low with the value of the RequestType field that appears in lowercase.

... | eval req_type_low = lower(RequestType)

Example 2: Create a new field, host_name_up, with the value of the HOST field that appears in uppercase.

... | eval host_name_up = upper(HOST)

Example 3: Create a new field, broken_url, with the value of the RequestURL field such that the new field value shows as a list of values split by the delimiter "/".

... | eval broken_url=split(RequestURL, "/")

Example 4: Create a new field, broken_url, with the value of the RequestURL field split by the delimiter "/". After this, create a new field, resource_root, with the first portion (index 1) of the broken_url value.

... | eval broken_url=split(RequestURL, "/")
| eval resource_root=mvindex(broken_url, 1)

Example 5: Create a new field, broken_url, with the value of the RequestURL field split by the delimiter "/" and then create a new field, resource_param, with the second-to-last portion of the broken_url value.

... | eval broken_url=split(RequestURL, "/")
| eval resource_param=mvindex(broken_url, -2)

Example 6: Create a new field, broken_url, with the value of the RequestURL field split by the delimiter "/" and then create a new field, resource_params, with a range of values (third-to-last portion to the last portion) of the broken_url value.

... | eval broken_url=split(RequestURL, "/") 
| eval resource_params=mvindex(broken_url, -3,-1)

For more details, see the long examples at eval search command.

Back to top ↑

extract

This search command can be used to extract field values or raw event data that it then assigns to new fields by using the Java regular expression capturing groups. The extract command can be used to specify a regular expression in such a way that it matches the target field value (or raw event data) that you want to extract and then assigns the extracted values to the new fields specified. The regular expression specified must exactly match the field value (or raw event data) in the search results.

Syntax

extract field=[<Source-Field>] "<Regex-Expression>"

In the preceding syntax, the following definitions apply:

• <Source-Field> refers to the source field name that you want to use to extract particular information. Specifying this information is optional. If you do not specify a field name, the raw event data is used to extract particular information.
• <Regex-Expression> refers to the Java regular expression (capturing groups) that you want to specify. This expression must be a combination of the regular expression and the new field or fields to which you want to assign the extracted information. This expression must be enclosed in double quotes (").
• [Expression] indicates it is optional.

Examples

Example 1: Extract the the log level data entry (example warning), and the corresponding component action data entry (example, VpxUtil_InvokeWithOpId) and assign the values to new fields, LogLevel and ComponentAction respectively.

... | extract field=".*?\[\d+\s+(?<LogLevel>\w+).*?\]\s+(?<ComponentAction>\w+).*"

Example 2: Extract two portions (host name and domain name) of the value of the HOST field and assign those values to two new fields, Hostname and Domainname.

... | extract field=HOST "(?<Hostname>[A-Za-z-]+)\.(?<Domainname>.+)"

For more details, see the long examples at extract search command.

Back to top ↑

extractkv

This search command extracts name=value pairs from raw event data depending on the delimiters specified. By default, name=value pairs are automatically extracted by the product, assuming the equals sign (=) as the separator. But when you run this command, name=value pairs are extracted depending on the options specified (kvdelim and pairdelim). Specifying these options is optional.

You can use this command to extract name=value pairs using other delimiters. A delimiter can be any character by which you extract name=value pairs (kvdelim) and name=value pair sets (pairdelim). You can use multiple characters as delimiters for extracting name=value pairs and name=value pair sets.

If you specify an option without its value, then by default a space ( ) is assumed as the delimiter for extracting name=value pair sets and the equals sign (=) is assumed as the delimiter for extracting name=value pairs. You can optionally limit the number of name=value pair sets to be extracted by using the limit parameter (the default is 50).

Syntax

extractkv [pairdelim="<Delimiters>"] [kvdelim="<Delimiters>"] [limit=<int>]

In the preceding syntax, the following definitions apply:

• [Expression] indicates it is optional.

• pairdelim="<Delimiters>" indicates the option for specifying the delimiters that separate name=value pair sets.

• kvdelim="<Delimiters>" indicates the option for specifying the delimiters that separate name=value pairs.

• limit=<int> indicates the integer value to use for limiting the number of name=value pairs and name=value pair sets.

Examples

Example 1: Extract name=value pairs where the name=value pair delimiter and name=value pair sets delimiter are set to default.

Example 2: Extract name=value pair sets separated by pipe and semi-colon (|;), where the delimiter for pairdelim (name=value pair sets) and limit options are set to default.

Example 3: Extract name=value pairs separated by colon (:), where the delimiter for kvdelim option (name=value pairs) is set to default.

Example 4: Extract a maximum of ten name=value pairs where the delimiter for kvdelim (name=value pairs) and the delimiter for pairdelim (name=value pair sets) are set to default.

Example 5: Extract name=value pairs separated by colon and equals sign (:=) and name=value pair sets separated by comma and semi-colon (,;).

... | extractkv pairdelim=",;" kvdelim=":="


For more details, see the long examples at extractkv search command.

Back to top ↑

fields

This search command retains (+) or removes (-) fields from search results based on the field list specified.

This command uses the following conventions:

• If you specify a plus sign (+), fields that match one of the fields specified in the command are retained.
• If you specify a minus sign (-), fields that match one of the fields specified in the command are removed.
• If you do not specify a plus (+) or a minus sign (-), the command assumes a plus sign (+).

Syntax

fields [+] <Field-List>

fields [-] <Field-List>

In the preceding syntax, the following definitions apply:

• [expression] indicates it is optional.
• <Field-List> refers to a comma-separated list of fields.

Examples

Example 1: Remove the fields destHost and ip from the search results.

For more details, see the long examples at fields search command.

Back to top ↑

filter

This command displays search results that match the specified filter function.

Syntax

filter <filter-function>

In the preceding syntax, <filter-function> can be one of the functions described in the following table:

isNotNull (<field>)

fieldexists (<field>)

match (<field>, "<string>")

isNumeric (<field>)

greaterthan (<field>, "<numeric-value>")

lessthan (<field>, "<numeric-value>")

Examples

Example 1: Filter search results containing numeric values for the field ResponseCode.

... | filter fieldexists(ResponseCode)

Example 2: Filter search results that do not contain the field Thread.

... | filter fieldexists(Thread)

Example 3: Filter search results matching the field RequestType with the value GET in a case-insensitive way.

... | filter match(RequestType, "GET")

Example 4: Filter search results matching the field RequestType with the value GET in a case-sensitive way.

... | filter matchcase(RequestType, "GET")

Example 5: Filter search results to display the field RequestType with the value matching the regular expression "....".

... | filter regex(RequestType, "....")

Example 6: Filter search results for the field ResponseCode with a value greater than 400.

... | filter greaterThan(ResponseCode, "400")

Example 7: Filter search results for the field ResponseCode with a value less than 400.

... | filter lessThan(ResponseCode, "400")

For more details, see the long examples at filter search command.

Back to top ↑

group

This search command groups events depending on the group options (conditions) specified to create a transaction of events. This command can help you correlate event data based on specific fields and provide a single transaction entry containing related event data from multiple systems, tiers, and so on.

Syntax

group [<field-list>] <group-options>*

In the preceding syntax, the following definitions apply:

• * indicates zero or more similar expressions.
• [expression] indicates it is optional.
• <field-list> refers to field names used for grouping the events into a single transaction. The field names can be separated by comma (,) or space.

• <group-options> refers to the following group options to specify for creating the grouped transaction. These group options are used as conditions for distributing transaction entries.

  Item	Syntax	Description
  maxspan	maxspan=<int>(<timescale>)?	Maximum time span (in seconds, minutes, hours) for grouping the transaction event entries. Default: 600 seconds (10 minutes) with a maximum of 7200 seconds (2 hours)
  maxpause	maxpause=<int>(<timescale>)?	Maximum interval (in seconds, minutes, hours) between the grouped transaction entries. Default: No limit, but cannot be greater than value of the maxspan option
  maxevents	maxevents=<int>	Maximum number of entries in a transaction. Default: 100 with a maximum limit of 10,000 events
  startswith	startswith=<filter-string>	Any string in the raw event data that must mark the start of the grouped transaction.
  endswith	endswith=<filter-string>	Any string in the raw event data that must mark the end of the grouped transaction.
  where, ? indicates zero or more similar expressions <int> refers to an integer value <timescale> refers to a time scale such as seconds, minutes, or hours. You can use one of the following time scale options in the command syntax: Seconds: s | sec | secs | second | seconds Minutes: m | min | mins | minute | minutes Hours: h | hr | hrs | hour | hours

Examples

Example 1: Group events occurring in the span of a maximum of 2 minutes.

... | group maxspan=2m

Example 2: Group events occurring with a time gap of 1 minute but limited to a maximum of two event entries.

... | group maxpause=1m maxevents=2

Example 3: Group data entries with the same HOST field value and with no gaps of longer than 5 seconds between two entries.

Example 4: Group data entries with a unique combination of userid and sessionid fields. The first and last entries are within the 25-second time gap. All sessions tied with some user ID are also associated in related transactions and the user ID is not required to be present in such log entries.

Example 5: Group data entries with the HOST field where the first entry contains signon and the last entry contains purchase. The startswith and endswith options mark the transaction boundary for log events.

... | group startswith=login endswith=logout

For more details, see the long examples at group search command.

Back to top ↑

head

This search command provides the first N number of search results. When you run this command, the events that were indexed first (the earliest records) are displayed in ascending order. You can specify a limit in the syntax to return the maximum number (N) of search results. If you run this command without specifying a limit, by default the product returns the first 10 results.

Syntax

head n 

OR

head limit=<integer>

In the preceding syntax, n or <integer> refers to an integer value that indicates the maximum number of records that you want to see.

Examples

Example 1: Return the first 10 records.

Example 2: Return the first 20 records.

... | head limit=20

Example 2: Return the first 2 records.

... | head 2

For more details, see the long example at head search command.

rare limit=<int> <field> [by <field>]

... | rare limit=1 RequestType by ClientIp

stats (<aggregate-function>)+

stats (<aggregate-function> [as <alias>])+ 

stats (<aggregate-function>)+ [by <field>]

stats (<aggregate-function> [as <alias>])+ [by <field>]

stats (<aggregate-function> [as <alias>])+ [by <field> [limit=<int>]]

stats (<aggregate-function> [as <alias>])+ [by <field> [sortby <option>]]

stats (<aggregate-function> [as <alias>])+ [by <field> [sortby <option>] 
[limit=<int>]]

... | stats count(RequestType)

... | stats count(RequestType) by ClientIp

... | stats sum(ResponseSize), avg(ResponseSize) by ClientIp sortby avg(ResponseSize)

... | stats min(ResponseSize), max(ResponseSize), avg(ResponseSize) 
stddev(ResponseSize) by ClientIp

... | stats avg(ResponseSize) by ClientIp limit=1

table [fields <field-list>+] [filter <filter-criterion>+]

tail N

tail limit=<integer>

top limit=<int> <field> [by <field>]

... | top limit=5 RequestType by ClientIp

... | top limit=1 RequestType

... | valmap field=ResponseSize light_load=100-149 mid_load=150-199 heavy_load=200-400

... | valmap field=ResponseSize light_load=100-129 mid_load=130-159 heavy_load=160-199 
default=unknown_load

... | valmap field=ResponseSize light_load=100-200 mid_load=150-300 heavy_load=300-400