Evaluate

Evaluate

Use evaluating commands to evaluate data directly within your search results. Perform statistical operations, extract and manipulate fields, perform SQL expression evaluations, and evaluate data in your search results.

abstract

This data-processing command produces an abstract (summary) of each search result. Splunk decides whether a line is important enough to be kept in the summary by determining how many of your search terms it contains, as well as how many of your search terms are on nearby lines. If a line contains a search term, its neighboring lines also partially match, and may be returned to provide context. When there are jumps between the lines selected, lines are prepended with "...".

Syntax

abstract [maxterms | maxlines]

Arguments

maxterms	maxterms=positive integer	Specifies the max number of terms a search result will keep for the abstract
maxlines	maxlines=positive integer(10)	Specifies the max number of lines that are kept for the abstract.

Examples

Splunk Web:

This example gets search results that contain the word "changes" and only show up to the best 5 lines of each search result.

addtotals

This data-processing command computes the arithmetic sum of all numeric fields for each result. Fields that begin with a "_" aren't processed. The resulting sum is then placed in a specified field (or "Total" if none is specified).

Syntax

addtotals [field_name]

Arguments

field_name

fieldname=field name(Total)

Name of a field to place the resulting sum. Default value is "Total" if no field is specified.

Examples

Splunk Web:

This example searches for the term "changes" on server1, and sums the numeric fields of each result. The resulting sums are then placed in the field "sum".

anomalousvalue

This data-processing command is useful for finding and summarizing results that may be irregular, or uncommon in your search results. It identifies values by how infrequently they appear, and by the number of standard deviations they are from the mean of the results.

Use anomalousvalue to find errors, and irregular behavior on a server that produces many common events. An irregular event can be found in any data that is mostly common and regular.

Syntax

anomalousvalue [action-option | pthresh-option]...

Arguments

pthresh-option

pthresh=number(0.01)

Specify a probability threshold (as a decimal) that must be met for a value to be considered anomalous.

action-option

action-option	action= annotate | filter | summary(filter)	Optionally specify the action for anomalousvalue to perform on values it finds to be anomalous. Default action is filter.
annotate	annotate	Adds a new field to the result containing the anomalous value. The new field contains the anomaly score for the anomalous value and is either: Anomaly_Score_Cat(<field>), where Cat stands for categorical, meaning that the value is rare; or, Anomaly_Score_Num(<field>), where Num is a numerical anomaly indicating that the value is outside some number of standard deviations from the numerical average of that field.
filter	filter	Causes your search results to be filtered to keep only those with anomalous values.
summary	summary	Produces a table summarizing the anomaly statistics for each field.

Examples

Splunk Web:

This example searches for all events on the host "reports", and returns only events with uncommon values.

bucket

The bucket command puts values of fields that are continuous and numerical into discrete sets. By default, the bucket command works on the _time field.

Important: The bucket command has two aliases: bin and discretize; these are just different names for the same command.

Note: The bucket argument is called by chart and timechart; the bucket command is only needed for statistical operations (see the stats command) that the chart and timechart commands cannot process.

Syntax

bucket [bucketing-option]... field as [new-field-name]

Arguments

field	field name	Name of field to take numerical values from.
new-field-name	field name	Name of the field to place discretized numerical values.

bucketing-option

bucketing-option	bins | span | start | end	Discretization options.
bins	bins=integer(20)	Sets the maximum number of discrete bins to build. If using the _time field, the default=300.
span	span=integer span-length	Sets the size of each bucket. Example =span=10 or span=2d or span=5m
start	start=integer	Sets the minimum number of numerical buckets.
end	end=integer	Sets the maximum number of numerical buckets.

span-length

span-length	ts-sec | ts-min | ts-hr | ts-day | ts-month	Time scale units.
ts-sec	s | sec | secs | second | seconds	Time scale in seconds.
ts-min	m | min | mins | minute | minutes	Time scale in minutes.
ts-hr	h | hr | hrs | hour | hours	Time scale in hours.
ts-day	d | day | days	Time scale in days.
ts-month	mon | month | months	Time scale in months.

Examples

Splunk Web:

Example 1: This example searches all events in the _internal index and sets the number of bins to 10. It returns a table of the number of raw events in the index that matches the max_size value.

Example 2: Return the average "thruput" of each "host" for each 5 minute time span.

CLI:

Example 3: This example returns the average thruput for each host for each 5 minute time span.

./splunk search "index=_internal group=per_host_thruput | bucket _time span=5m | stats avg(kbps) by _time" 

convert

Use convert to temporarily change the format of field values into numeric values at search time. For example, say you want to create a report showing the timestamps in human readable format, and your events contain a timestamp that is in epoch time format. Use convert with the ctime or mktime option to convert the timestamp into a human readable format for your report (ctime and mktime conversions use the timeformat modifier by default. The default format is: "%m/%d/%Y %H:%M:%S").

If you rename a fields using an as argument, the original field's name is left in tact in the index.

Syntax

convert [convert-function] as field

Arguments

field

string (field name)

field* | *field*).

convert-function

convert-function	auto | ctime | dur2sec | memk | none | num | rmunit	Specify the conversion function to use.
auto	auto=(field)	Automatically converts the field(s) using the most appropriate known conversion type. Can convert multiple fields using the * wildcard.
ctime	ctime=(field)	Convert epoch time format field values to ASCII time format. Specify a list of fields to apply the time format conversion. You can use wildcards when specifying fields.
dur2sec	dur2sec=(field)	Converts a duration of D+HH:MM:SS format to seconds.
memk	memk=(field)	MB|GB to KB.
mktime	mktime(field)	Convert ASCII time format field values to epoch time format. Specify a list of fields to apply the time format conversion. You can use wildcards when specifying fields.
mstime	mstime=(field)	Convert a MM:SS.SSS formatted field to seconds.
none	none=(field)	Specify fields that should not be matched in conversions (exceptions). Use * to specify multiple fields.
num	num=(field)	Automatically converts field(s) using the best known conversion, except removes non-convertible values. Use * to specify multiple fields.
rmunit	rmunit=(field)	Looks for numbers in the beginning of a field, and removes the trailing text. Use * to specify multiple fields.

Examples

Splunk Web:

This example attempts to convert every field (that doesn't start with an '_') except for the field 'foo'. None tells convert to ignore a field.

This example changes all memory amounts into kilobytes. Assumes that a number by itself specifies kB, numbers with 'm' indicates MB, and numbers with 'g' indicate GB.

This example converts epoch time to human readable time.

CLI:

This example changes the sendmail syslog duration format of [D+HH:MM:SS] to seconds, e.g. '00:10:15' -> '615' for the xdelay field.

./splunk search "* | convert dur2sec(delay)"

This example expects the value to be a number (can be floating point) followed by any string. Will remove the string, i.e. '212 sec' -> '212'.

./splunk search "* | convert rmunit(duration)"

eval

This data-processing command performs an arbitrary expression evaluation using SQLite (Refer to the SQLite online documentation for a SQLlite expressions reference) on search results and temporarily changes the appearance of the specified field at search time. The result is written to the field: dest_field by default. If the evaluation of the field is unsuccessful, eval will erase the existing field.

Note: eval does not support the SQLite commands "|" and "| |" (double-bar and single-bar). This is because "|" is used in Splunk's search language to separate commands in a search string.

Syntax

eval dest_field =SQLite expression

Arguments

dest_field	field name	Specify a new or existing field to write the results of the SQLite expression to. Eval will over-write the values of an existing field, and will create a new field if the specified field doesn't already exist.
SQLite expression	The SQLite expression to evaluate. The expression uses the SQLlite syntax

Examples

Splunk Web:

This example composes a full name by concatenating the first_name field, a space character, and the last_name field into the full_name field.

CLI:

This example is the CLI version of the above example.

./splunk search '* | eval full_name = first_name." ".last_name'

fields

Remove fields from search results (similar to how an SQL select statement does). Use fields to filter data in your search results to only include specific information you are interested in. Use fields to make search results more readable, and to make reporting faster. For example, if you are only interested in reporting on the host and ip fields of your search results, pipe your search to: | fields host, ip (this keeps the internal fields like _time, _raw, etc.).

See the SQLite online documentation for help with SQLite arguments, and filtering expressions.

Note: The fields picker is disabled when you use fields in a search in Splunk Web. To use the fields picker, remove the fields command from your search.

Syntax

fields [+ | -] field,field,...

Arguments

+	Only keep the fields listed after + in your search results. Splunk removes all internal fields (fields beginning with _underscores) from your search results when you use +. Specify a list of fields without a + argument to keep all internal fields along with the list of fields you specify.
-	Remove fields listed after - from your search results.
field	A comma-separated list of fields. You can use wildcards.

Examples

Splunk Web:

This example removes all fields (including internal fields) except host and ip from your search results.

This example removes the host and ip fields from your search results and leaves all others untouched.

CLI:

This example keeps all fields that end with "_kbps" (and all internal fields).

./splunk search "* | fields *_kbps"

Note: The fields command replaces the deprecated select functionality to display chosen fields; instead of using sourcetype=foo | select * to display all fields, the preferred method is to use sourcetype=foo | fields *.

fillnull

This data-processing command is used to replace null values with a specified value. Null values are values that are missing in one result, but are present in other results of a search.

Syntax

fullnull [value=string]

Arguments

string

string(0)

A specified string to fill null values with. If nothing is specified, "0" is used.

Examples

Splunk Web:

This example searches for events with the sourcetype "web", and produces a timechart count by host. Then fills all null values with "NULL".

kmeans

This data-processing command performs k-means clustering on selected fields. If no fields are selected, then clustering is performed on all numerical fields. When applied, this command will move events in the same cluster next to each other, and you can optionally have the cluster number displayed with each event.

K-means clustering is a statistical algorithm used to cluster objects (in this case events) based on attributes. The objects are clustered into partitions in order to find the centers of natural clusters in data (events in this case).

Syntax

kmeans [kmeans-option]... field-list

Arguments

field-list

field,...,field

Selected fields to perform k-means clustering on. If none are specified, then kmeans will process all numerical fields (num).

kmeans-option

kmeans-option	reps | iters | tol | k | cnumfield | distype | showlabel	Options for kmeans.
reps	reps=integer(10)	Specify the number of times to repeat kmeans using random starting clusters.
iters	maxiters=integer(10000)	Specifies the maximum number of iterations to allow before convergence failure.
k	k=integer [-integer****] (k=2)	Specifies the number of initial clusters. You can specify a range. Summary data will be given for each value in a range.
cnumfield	cfield=field(clusternum)	Specifies a field name for the cluster number for each event. If no field name is given, then "clusternum" is applied as default.
distype	dt=( L1 | L1NORM | CITYBLOCK | CB | L2 | L2NORM | SQ | SQEUCLIDEAN | COS | COSINE)(L2NORM)	Specify a distance metric to use. L1, L1NORM, CITYBLOCK, and CB all designate L1 norm/cityblock distance. L2, L2NORM, SQ, SQEUCLIDEAN all designate L2NORM/squared euclidean distance. COS, and COSINE designate cosine distance.
showlabel	showlabel=(T | F)(F)	If set, will cause the cluster number to be added to the data summary.

Examples

Splunk Web:

This example searches for all events on myboxen, and attempts to find 4 groups based on the values of the date_hour and date_minute fields.

outlier

This data-processing command removes or truncates outlying numerical values in selected fields. If no fields are specified, then outlier will attempt to process all fields.

Syntax

outlier[outlier-option] [field-list]

Arguments

field-list

field,field,...

List of fields to process.

outlier-option

outlier-option	type | action | param | uselower	Options for outlier.
type	type=IQR(IQR)	Specifies the type of outlier detection. Currently only IQR.
action	action=(RM | REMOVE | TF | TRANSFORM)(RM)	Specifies what action to perform on outliers. RM or REMOVE, removes the event containing the outlying numerical value. TF or TRANSFORM, truncates the outlying value to the using the specified threshold for outliers. Then prepends the value with "000". If no action is specified then the default action is to remove the outlying values.
param	param=number(2.5)	Specifies the threshold for outlier detection. For type=IQR, an outlier is defined as: a numerical value that is outside of the param number multiplied by the inter-quartile range.
uselower	uselower=(T | F)(F)	If set, will cause outlier to search for outlying values below the median.

Examples

Splunk Web:

This example searches for 404 on host: webserver. Creates a timechart and averages the cpu_seconds by host. Then truncates outlying values to remove data that may distort the timechart's axis.

rename

Rename a field, or number of fields (using a wildcard expression). If both the source and destination fields are wildcard expressions with the same number of wildcards, then all fields represented in the wildcard expressions will be renamed.

Syntax

rename original-field-name(s) as new-field-name(s)

Arguments

original-field-name(s)	field | wildcarded field (*field, field*, fie*ld)	Name of field or fields to rename. You can use a wildcard ("*") expression to specify many fields.
new-field-name(s)	field | wildcarded field (*field, field*, fie*ld)	Name to rename original field(s) as. You can use a wildcard ("*") expression to specify many names.

Examples

Splunk Web:

This example searches for the word error, renames the _ip field as IPAddress, and renames the _raw field as RawTest.

CLI:

This example shows the same example as above, but also shows that you can pipeline rename any number of times to rename any number of fields.

./splunk search "error | rename _ip as IPAddress | rename _raw as RawText"

replace

Replace values of fields with new values. You can use wildcards (*) to specify many values to replace, or replace many values with. When using wildcards, there must be a matching number of values in each list (to replace, and to be replaced with).

Syntax

replace ( orig-value-list WITH new-value-listl) ( IN field-list)

Arguments

orig-value-list	value,value,...	Space or comma-separated list of values to be replaced. You can use wildcards to specify multiple values.
new-value-list	value,value,...	Space or comma-separated list of values to be replaced. You can use wildcards to specify multiple values.
field-list	field,field,...	Space or comma-separated list of fields to replace values within.

Examples

Splunk Web:

This example replaces any host value ending with "localhost" to just be "localhost".

CLI:

This example replaces any values of "0" in the msg_level field with "Critical", and any values of "1" with "Error".

./splunk search "* | replace 0 with Critical, 1 with Error in msg_level"