Converts events generated by streaming search commands into metric data points and inserts the data into a metric index on the indexers.
You can use the
meventcollect command only if your role has the
run_mcollect capability. See Define roles on the Splunk platform with capabilities in Securing Splunk Enterprise.
The required syntax is in bold.
- | meventcollect index=<string>
- [ file=<string> ]
- [ split=<bool> ]
- [ spool=<bool> ]
- [ prefix_field=<string> ]
- [ host=<string> ]
- [ source=<string> ]
- [ sourcetype=<string> ]
- [ <field-list> ]
- Syntax: index=<string>
- Description: Name of the metric index where the collected metric data is added.
- Syntax: <field>, ...
- Description: A list of dimension fields. Required if
split=true. Optional if
split=false. If unspecified (which implies that
meventcollecttreats all fields as dimensions for the data point, except for the
prefix_field, and all internal fields.
- Default: No default value
- Syntax: split=<bool>
- Description: Determines how
meventcollectidentifies the measures in an event. See How to use the split argument.
- Default: false
- Syntax: spool=<bool>
- Description: If set to true,
meventcollectwrites the metrics data file to the Splunk spool directory,
$SPLUNK_HOME/var/spool/splunk, where the file is indexed automatically. If set to false,
meventcollectwrites the file to the
$SPLUNK_HOME/var/run/splunkdirectory. The file remains in this directory unless further automation or administration is done.
- Default: true
- Syntax: prefix_field=<string>
- Description: Only applicable when
split=true. If specified,
meventcollectignores any data point with that field missing. Otherwise,
meventcollectprefixes the field value to the metric name. See Set a prefix field.
- Default: No default value
- Syntax: host=<string>
- Description: The name of the host that you want to specify for the collected metrics data. Only applicable when
- Default: No default value
- Syntax: source=<string>
- Description: The name of the source that you want to specify for the collected metrics data.
- Default: If the search is scheduled, the name of the search. If the search is ad-hoc,
meventcollectwrites the name of the file to the
var/spool/splunkdirectory containing the search results.
- Syntax: sourcetype=<string>
- Description: The name of the source type that you want to specify for the collected metrics data.
- Default: metrics_csv
Do not change this setting without assistance from Splunk Professional Services or Splunk Support. Changing the source type requires a change to the
You use the
meventcollect command to convert streaming events into metric data to be stored in a metric index on the indexers. The metrics data uses a specific format for the metrics fields. See
Metrics data format in Metrics.
Only streaming commands can precede the
meventcollect command so that results can be ingested on the indexers. If you would like to run a search that uses transforming commands to generate metric data points, use
mcollect instead of
meventcollect command causes new data to be written to a metric index for every run of the search. In addition, if you run an
meventcollect search over large amounts of data, it potentially can overwhelm indexers and indexer clusters that do not have a significant amount of capacity.
All metrics search commands are case sensitive. This means, for example, that
meventcollect treats as the following as three distinct values of
The Splunk platform cannot index metric data points that contain
metric_name fields which are empty or composed entirely of white spaces.
How to use the split argument
split argument determines how
meventcollect identifies the measurement fields in your search. It defaults to
split=false, your search needs to explicitly identify its measurement fields. If necessary it can use
eval conversions to do this.
- If you have single-metric events, your
meventcollectsearch must produce results with a
metric_namefield that provides the name of the measure, and a
_valuefield that provides the measure's numeric value.
- If you have multiple-metric events, your
meventcollectsearch must produce results that follow this syntax:
metric_name:<metric_name>=<numeric_value>. Each of these fields will be treated as a measurement.
meventcollecttreats the remaining fields as dimensions.
When you set
split=true, you use
field-list to identify the dimensions in your search.
meventcollect converts any field that is not in the
field-list into a measurement. The only exceptions are internal fields beginning with an underscore and the
prefix_field, if you have set one.
Set a prefix field
prefix_field argument to apply a prefix to the metric fields in your event data.
For example, if you have the following data:
type=cpu usage=0.78 idle=0.22
You have two metric fields,
Say you include the following in an
mcatalog search of that data:
Because you have set
split = true the Splunk software automatically converts those fields into measures, because they are not otherwise identified in a
<field-list>. Then it applies the value of the specified
prefix_field as a prefix to the metric field names. In this case, because you have specified the
type field as the prefix field, its value,
cpu, becomes the metric name prefix. The results look like this:
1: Collect metrics.log data into a metrics index
The following example shows you how to collect metrics log data into a metric index called 'my_metric_index'.
| eval prefix = group + "." + name
| meventcollect index=my_metric_index split=true prefix_field=prefix name group
This documentation applies to the following versions of Splunk® Enterprise: 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.2.0, 8.2.1