Splunk® Enterprise

Search Reference

Download manual as PDF

Download topic as PDF

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.

Syntax

meventcollect index=<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 if split=false. If unspecified (which implies that split=false), all fields are treated as dimensions for the data point, except for the metric_name, prefix_field, and all internal fields.
Default: No default value

Optional arguments

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, 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/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, 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
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, the name of the file that is written to the var/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.

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 a metric_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. 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

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

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:

_time user metric_name:jobs metric_name:latency
1563318689 admin 25 3.8105555555555575
1563318689 splunk-system-user 129 0.2951162790697676

See also

Commands
collect
mcollect
PREVIOUS
metasearch
  NEXT
mstats

This documentation applies to the following versions of Splunk® Enterprise: 8.0.0


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters