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.
meventcollect index=<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
split=false), all fields are treated 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, the metrics data file is written to the Splunk spool directory,
$SPLUNK_HOME/var/spool/splunk, where the file is indexed automatically. If set to false, the file is written 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, any data point with that field missing is ignored. Otherwise, the field value is prefixed 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, the name of the file that is written 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.
All metrics search commands are case sensitive. This means, for example, that
meventcollect treats as the following as three distinct values of
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. The remaining fields will be treated 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'.
index=_internal source=*/metrics.log | eval prefix = group + "." + name | meventcollect index=my_metric_index split=true prefix_field=prefix name group
2: Generate metric data points that break out jobs and latency metrics by user
The following example specifies the metrics that should appear in the resulting metric data points, and splits them by user. Note that it does not use the
split argument, so the search has to use a
rename conversion to explicitly identify the measurements that will appear in the data points.
index="_audit" search_id info total_run_time
| stats count(search_id) as jobs avg(total_run_time) as latency by user
| rename jobs as metric_name:jobs latency as metric_name:latency
| meventcollect index=mcollect_test
Here are example results of that search:
This documentation applies to the following versions of Splunk® Enterprise: 8.0.0, 8.0.1, 8.0.2, 8.0.3