mcatalog
The mcatalog
command is an internal, unsupported, experimental command. See
About internal commands.
Description
The mcatalog
command performs aggregations on the values in the metric_name
and dimension
fields in the metric indexes.
Syntax
| mcatalog [prestats=<bool>] [append=<bool>] ( <values"("<field> ")"> [AS <field>] )
[WHERE <logical-expression>] [ (BY|GROUPBY) <field-list> ]
Required arguments
- values (<field>)
- Syntax: values(<field>) [AS <field>]
- Description: Returns the list of all distinct values of the specified field as a multivalue entry. The order of the values is lexicographical. See Usage.
Optional arguments
- append
- Syntax: append=<bool>
- Description: Valid only when
prestats=true
. This argument runs themcatalog
command and adds the results to an existing set of results instead of generating new results. - Default: false
- <field-list>
- Syntax: <field>, ...
- Description: Specify one or more fields to group results.
- <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, and index expressions. 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
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 ( = )
ornot 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 oferror=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 mcatalog
command to search metrics data. The metrics data uses a specific format for the metrics fields. See
Metrics data format in Metrics. The _values
field is not allowed with this command.
The mcatalog
command is a generating command for reports. Generating commands use a leading pipe character. The mcatalog
command must be the first command in a search pipeline, except when append=true
.
All metrics search commands are case sensitive. This means, for example, that mcatalog
treats as the following as three distinct values of metric_name
: cap.gear
, CAP.GEAR
, and Cap.Gear
.
If your role does not have the list_metrics_catalog
capability, you cannot use mcatalog
.
See About defining roles with capabilities in the Securing Splunk Enterprise manual.
WHERE
Use the WHERE clause to filter by supported dimensions.
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.
Group by
You can group by dimension
and metric_name
fields.
The mcatalog
command does not allow grouping by time ranges. The
Time dimensions
The mcatalog
command does not recognize the following time-related dimensions.
Unsupported dimensions date_hour
date_mday
date_minute
date_month
date_second
date_wday
date_year
date_zone
metric_timestamp
time
timeendpos
timestamp
timestartpos
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.
You can specify a custom sort order that overrides the lexicographical order. See the blog Order Up! Custom Sort Orders.
Examples
1. Return all of the metric names in a specific metric index
Return all of the metric names in the new-metric-idx
.
| mcatalog values(metric_name) WHERE index=new-metric-idx
2. Return all metric names in the default metric indexes associated with the role of the user
If the user role has no default metric indexes assigned to it, the search returns no events.
| mcatalog values(metric_name)
3. Return all IP addresses for a specific metric_name among all metric indexes
Return of the IP addresses for the login.failure
metric name.
| mcatalog values(ip) WHERE index=* AND metric_name=login.failure
4. Returns a list of all available dimensions in the default metric indexes associated with the role of the user
| mcatalog values(_dims)
makejson | noop |
This documentation applies to the following versions of Splunk® Enterprise: 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.1.13, 8.1.14, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12
Feedback submitted, thanks!