mstats

Description

Use the mstats command to analyze metrics. This command performs statistics on the measurement, metric_name, and dimension fields in metric indexes. The mstats command is optimized for searches over a single or small number of metric names, rather than searching across all metric names. Both historical searches and real-time searches are supported. For a real-time search with a time window, a historical search is run first to backfill the data.

Syntax

| mstats [prestats=<bool>] [append=<bool>] [backfill=<bool>] [update_period=<integer>] <stats-func>...
WHERE [<logical-expression>]... <metric_name=<string>>... [ (BY|GROUPBY) <field-list> ] [<span-length>]

Required arguments

metric_name

Syntax: metric_name=<string>...

Description: The metric_name fields that you want to perform statistics on. You can specify multiple fields by either specifying each metric_name field individually or using a wildcard character to specify metric_name fields with similar names.

<stats-func>

Syntax: count(_value) | <function>(_value) [AS <string>]

Description: Specify a basic count of the _value field or a function on the _value field. The _value field uses a specific format to store the numeric value of the metric. See Usage. You can specify one or more functions. You can rename the result of the function using AS, unless prestats=true.

The following table lists the supported functions by type of function. Use the links in the table to see descriptions and examples for each function. For an overview about using functions with commands, see Statistical and charting functions.

Type of function	Supported functions and syntax
Aggregate functions	avg() count() max() median() min()	perc<int> range() stdev() stdevp()	sum() sumsq() upperperc<int> var() varp()
Event order functions	earliest()	latest()

Optional arguments

append

Syntax: append=<bool>

Description: Valid only when prestats=true. This argument runs the mstats command and adds the results to an existing set of results instead of generating new results.

Default: false

backfill

Syntax: backfill=<bool>

Description: Valid only with windowed real-time searches. When backfill=true, the mstats command runs a search on historical data to backfill events before searching the in-memory real-time data.

Default: true

<field-list>

Syntax: <field>, ...

Description: Specifies one or more fields to group the results by. Required if using the BY or GROUPBY clause.

<logical-expression>

Syntax: <time-opts>|<search-modifier>|((NOT)? <logical-expression>)|<index-expression>|<comparison-expression>|(<logical-expression> (OR)? <logical-expression>)

Description: Includes time and search modifiers, comparison expressions, and index expressions. See the sections below for descriptions of each of these logical expression components.

Does not support CASE or TERM directives. You also cannot use the WHERE clause to search for terms or phrases.

prestats

Syntax: prestats=true | false

Description: Specifies whether to use the prestats format. The prestats format is a Splunk internal format that is designed to be consumed by commands that generate aggregate calculations. When using the prestats format you can pipe the data into the chart, stats, or timechart commands, which are designed to accept the prestats format. When prestats=true, AS instructions are not relevant. The field names for the aggregates are determined by the command that consumes the prestats format and produces the aggregate output.

Default: false

<span-length>

Syntax: span=<int><timescale>

Description: The span of each time bin. If discretizing based on the _time field or if used with a <timescale>, the span-length is treated as a time range. If not, this is an absolute bucket length. If you do not specify a <span-length>, the default is auto, which means that the number of time buckets adjusts to produce a reasonable number of results. For example if initially seconds are used for the <timespan> and too many results are being returned, the <timespan> is changed to a longer value, such as minutes, to return fewer time buckets.

<timescale>

Syntax: <sec> | <min> | <hr> | <day> | <month>

Description: Time scale units. For the mstats command, the <timescale> does not support subseconds.

Default: sec

Time scale	Syntax	Description
<sec>	s | sec | secs | second | seconds	Time scale in seconds.
<min>	m | min | mins | minute | minutes	Time scale in minutes.
<hr>	h | hr | hrs | hour | hours	Time scale in hours.
<day>	d | day | days	Time scale in days.
<month>	mon | month | months	Time scale in months.

update_period

Syntax: update_period=<integer>

Description: Valid only with real-time searches. Specifies how frequently, in milliseconds, the real-time summary for the mstats command is updated. A larger number means less frequent updates to the summary and less impact on index processing.

Default: 1000 (1 second)

Logical expression options

<comparison-expression>

Syntax: <field><comparison-operator><value> | <field> IN (<value-list>)

Description: Compare a field to a literal value or provide a list of values that can appear in the field.

<index-expression>

Syntax: "<string>" | <term> | <search-modifier>

Description: Describe the events you want to retrieve from the index using literal strings and search modifiers.

<time-opts>

Syntax: [<timeformat>] (<time-modifier>)*

Description: Describe the format of the starttime and endtime terms of the search

Comparison expression options

<comparison-operator>

Syntax: = |  != | < | <= | > | >=

Description: You can use comparison operators when searching field/value pairs. Comparison expressions with the equal ( = ) or not equal ( != ) operator compare string values. For example, "1" does not match "1.0". Comparison expressions with greater than or less than operators < > <= >= numerically compare two numbers and lexicographically compare other values. See Usage.

<field>

Syntax: <string>

Description: The name of a field.

<value>

Syntax: <literal-value>

Description: In comparison-expressions, the literal number or string value of a field.

<value-list>

Syntax: (<literal-value>, <literal-value>, ...)

Description: Used with the IN operator to specify two or more values. For example use error IN (400, 402, 404, 406) instead of error=400 OR error=402 OR error=404 OR error=406

Index expression options

<string>

Syntax: "<string>"

Description: Specify keywords or quoted phrases to match. When searching for strings and quoted strings (anything that's not a search modifier), Splunk software searches the _raw field for the matching events or results.

<search-modifier>

Syntax: <sourcetype-specifier> | <host-specifier> | <source-specifier> | <splunk_server-specifier>

Description: Search for events from specified fields. For example, search for one or a combination of hosts, sources, and source types. See searching with default fields in the Knowledge Manager manual.

<sourcetype-specifier>

Syntax: sourcetype=<string>

Description: Search for events from the specified sourcetype field.

<host-specifier>

Syntax: host=<string>

Description: Search for events from the specified host field.

<source-specifier>

Syntax: source=<string>

Description: Search for events from the specified source field.

<splunk_server-specifier>

Syntax: splunk_server=<string>

Description: Search for events from a specific server. Use "local" to refer to the search head.

Time options

For a list of time modifiers, see Time modifiers for search.

<timeformat>

Syntax: timeformat=<string>

Description: Set the time format for starttime and endtime terms.

Default: timeformat=%m/%d/%Y:%H:%M:%S.

<time-modifier>

Syntax: starttime=<string> | endtime=<string> | earliest=<time_modifier> | latest=<time_modifier>

Description: Specify start and end times using relative or absolute time.

Note: You can also use the earliest and latest attributes to specify absolute and relative time ranges for your search. For more about this time modifier syntax, see About search time ranges in the Search Manual.

starttime

Syntax: starttime=<string>

Description: Events must be later or equal to this time. Must match timeformat.

endtime

Syntax: endtime=<string>

Description: All events must be earlier or equal to this time.

Usage

You use the mstats command to search metrics data. The metrics data uses a specific format for the metrics fields. See Metrics data format in Metrics.

The mstats command is a generating command. Generating commands use a leading pipe character. The mstats command must be the first command in a search pipeline, except when append=true.

Wildcard characters

The mstats command supports wildcard characters in any search filter. However, you cannot use wildcard characters in the GROUP BY clause or in the _value field.

Aggregations

Numeric aggregations are only allowed on the _value field. Aggregations are not allowed for any other field, including the _time field.

Filtering

Filtering on the _value field is not allowed.

Group by

To group by time, you must specify a timespan using the <span-length> argument for grouping time buckets. For example, span=1hr or span=auto. Grouping by the _time field is not allowed.

You can also group by the dimension and metric_name fields.

You cannot group by the _value field.

The <span-length> argument is separate from the BY clause, and can be placed at any point in the search between clauses.

WHERE

Use the WHERE clause to filter by any dimensions or by metric name. For performance reasons, the mstats command requires the WHERE clause to specify a metric name.

If you do not specify an index name in the WHERE clause, the mcatalog command returns results from the default metrics indexes associated with your role. If you do not specify an index name and you have no default metrics indexes associated with your role, mcatalog returns no results. To search against all metrics indexes use WHERE index=*.

For more information about defining default metrics indexes for a role, see Add and edit roles with Splunk Web in Securing Splunk Enterprise.

Lexicographical order

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, this is almost always UTF-8 encoding, which is a superset of ASCII.

• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 70, 100 are sorted lexicographically as 10, 100, 70, 9.
• Uppercase letters are sorted before lowercase letters.
• Symbols are not standard. Some symbols are sorted before numeric values. Other symbols are sorted before or after letters.

Examples

1. Calculate a single metric grouped by time

Return the average value of the aws.ec2.CPUUtilization metric in the mymetricdata metric index. Bucket the results into 30 second time spans.

| mstats avg(_value) WHERE index=mymetricdata AND metric_name=aws.ec2.CPUUtilization span=30s

2. Combine metrics with different metric names

Return the average value of both the aws.ec2.CPUUtilization metric and the os.cpu.utilization metric. Group the results by host and bucket the results into 1 minute time spans. Both metrics are combined and considered a single metric series.

| mstats avg(_value) WHERE index=mymetricdata AND (metric_name=aws.ec2.CPUUtilization OR metric_name=os.cpu.utilization) span=1m BY host

3: Use prestats=t mode with the timechart command

Return a timechart of the number of aws.ec2.CPUUtilization metric data points for each day.

| mstats prestats=t count WHERE index=mymetricdata AND metric_name=aws.ec2.CPUUtilization span=1d | timechart span=1d count

4. Specify multiple aggregations on multiple metrics

Return the average and maximum of the network recieved bytes count and network sent bytes count. Group the results by metric_name.

| mstats avg(_value) AS "Average" max(_value) AS "Maximum" WHERE index=mymetricdata AND (metric_name=gcp.appengine.system.network.received_bytes_count OR metric_name=gcp.appengine.system.network.sent_bytes_count) span=1m BY metric_name

See also

Overview of metrics in Metrics