meventcollect
Description
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.
This command is considered risky because, if used incorrectly, it can pose a security risk or potentially lose data when it runs. As a result, this command triggers SPL safeguards. See SPL safeguards for risky commands in Securing the Splunk Platform.
Syntax
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> ]
Required arguments
- index
- Syntax: index=<string>
- Description: Name of the metric index where the collected metric data is added.
- field-list
- Syntax: <field>, ...
- Description: A list of dimension fields. Required if
split=true
. Optional ifsplit=false
. If unspecified (which implies thatsplit=false
),meventcollect
treats all fields as dimensions for the data point, except for themetric_name
,prefix_field
, and all internal fields. - Default: No default value
Optional arguments
- file
- Syntax: file=<string>
- Description: The file name where you want the collected metric data to be written. Only applicable when
spool=false
. You can use a timestamp or a random number for the file name by specifying either file=$timestamp$ or file=$random$. - Default: $random$_metrics.csv
- split
- Syntax: split=<bool>
- Description: Determines how
meventcollect
identifies the measures in an event. See How to use the split argument. - Default: false
- spool
- Syntax: spool=<bool>
- Description: If set to true,
meventcollect
writes the metrics data file to the Splunk spool directory,$SPLUNK_HOME/var/spool/splunk
, where the file is indexed automatically. If set to false,meventcollect
writes the file to the$SPLUNK_HOME/var/run/splunk
directory. The file remains in this directory unless further automation or administration is done. - Default: true
- prefix_field
- Syntax: prefix_field=<string>
- Description: Only applicable when
split=true
. If specified,meventcollect
ignores any data point with that field missing. Otherwise,meventcollect
prefixes the field value to the metric name. See Set a prefix field. - Default: No default value
- host
- Syntax: host=<string>
- Description: The name of the host that you want to specify for the collected metrics data. Only applicable when
spool=true
. - Default: No default value
- source
- 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,
meventcollect
writes the name of the file to thevar/spool/splunk
directory containing the search results.
- sourcetype
- 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
props.conf
file.
Usage
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
.
The 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 metric_name
: cap.gear
, CAP.GEAR
, and Cap.Gear
.
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
The split
argument determines how meventcollect
identifies the measurement fields in your search. It defaults to false
.
When split=false
, your search needs to explicitly identify its measurement fields. If necessary it can use rename
or eval
conversions to do this.
- If you have single-metric events, your
meventcollect
search must produce results with ametric_name
field that provides the name of the measure, and a_value
field that provides the measure's numeric value. - If you have multiple-metric events, your
meventcollect
search must produce results that follow this syntax:metric_name:<metric_name>=<numeric_value>
. Each of these fields will be treated as a measurement.meventcollect
treats 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.
When you set split=allnums
, meventcollect
treats all numeric fields as metric measures and all non-numeric fields as dimensions. You can optionally use field-list
to declare that meventcollect
should treat certain numeric fields in the events as dimensions.
Set a prefix field
Use the 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, usage
and idle
.
Say you include the following in an mcatalog
search of that data:
...split=true prefix_field=type...
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:
metric_name:cpu.usage | metric_name:cpu.idle |
---|---|
0.78 | 0.22 |
Examples
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
See also
metasearch | mpreview |
This documentation applies to the following versions of Splunk Cloud Platform™: 9.2.2406 (latest FedRAMP release), 8.2.2112, 8.2.2202, 9.0.2205, 8.2.2201, 8.2.2203, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403
Feedback submitted, thanks!