Search commands for machine learning
The Splunk Machine Learning Toolkit (MLTK) includes several custom machine learning search commands. You can use these ML-SPL commands on any Splunk platform instance where MLTK is installed.
ML-SPL commands implement the following classic machine learning and statistical learning tasks:
ML-SPL command name | Description |
---|---|
fit
|
Fit and apply a machine learning model to search results. |
apply
|
Apply a machine learning model that was learned using the fit command.
|
summary
|
Return a summary of a machine learning model that was learned using the fit command.
|
listmodels
|
Return a list of machine learning models that were learned using the fit command.
|
deletemodel
|
Delete a machine learning model that was learned using the fit command.
|
sample
|
Randomly sample or partition events. |
score
|
Run statistical tests to validate model outcomes. |
ML-SPL commands follow the same syntax as other SPL commands in the Splunk platform. For more details on this syntax, see Understanding SPL syntax. in the Search Reference manual.
You can also configure the performance costs of the fit
and apply
commands. For details, see Configure algorithm performance costs.
The fit and apply commands work on relative searches with relative time ranges, but will not complete on real-time searches.
The ML-SPL commands along with the available MLTK algorithms can be viewed as a quick reference guide. You You can download a PDF of the Splunk Machine Learning Toolkit Quick Reference Guide in English or Japanese:
- Splunk Machine Learning Toolkit Quick Reference Guide, English
- Splunk Machine Learning Toolkit Quick Reference Guide, Japanese
fit command
Use the fit
command to fit and apply a machine learning model to search results. The syntax is the same for supervised (labeled data) and unsupervised (unlabeled data) learning.
The fit
command modifies the model. The command is considered risky because running it can cause performance issues. As a result, this command triggers SPL safeguards. To learn more, see
Search commands for machine learning safeguards.
Syntax
The first argument for the algorithm is required. The options following the algorithm vary depending on the algorithm chosen:
fit <algorithm> [option_name]=[option_value]... [into <model_name>]
Some algorithms require a response-field
:
fit <algorithm> [option_name]=[option_value]...<response-field> [into <model_name>]
Some algorithms require an explanatory-field
:
fit <algorithm> [option_name]=[option_value]...<explanatory-field> [into <model_name>]
Some algorithms require both a response-field
and an explanatory-field
. The from
field is only required if both the response-field
and explanatory-field
are present:
fit <algorithm> [option_name]=[option_value]...<response-field> from <explanatory-field> [into <model_name>]
Use the into
keyword to store the learned model in an artifact that can later be applied to new search results with the apply
command.
Not all algorithms support saved models. For details on all the algorithms that ship with MLTK, see Algorithms in the Splunk Machine Learning Toolkit.
Examples
The following example fits a LinearRegression model to predict errors
using _time
:
... | fit LinearRegression errors from _time
The following example fits a LinearRegression model to predict errors
using _time
and saves it into a model named errors_over_time
:
... | fit LinearRegression errors from _time into errors_over_time
The following example fits a LogisticRegression model to predict a categorical response from numerical measurements:
... | fit LogisticRegression species from petal_length petal_width sepal_length sepal_width
apply command
Use the apply
command to compute predictions for the current search results based on a model that was learned using the fit
command. The apply
command can be used on different search results than those used when fitting the model, but the results should have an identical list of fields.
Syntax
apply <mode_name> [as <output_field>]
Use the as
keyword to rename the field added to search results by the model.
Examples
The following example applies a learned LinearRegression model named errors_over_time
:
... | apply errors_over_time
The following example renames the output of the model to predicted_errors
:
... | apply errors_over_time as predicted_errors
summary command
Use the summary
command to return a summary of a machine learning model that was learned using the fit
command. The summary is algorithm specific. For example, the summary for the LinearRegression algorithm is a list of coefficients. The summary for the LogisticRegression algorithm is a list of coefficients for each class.
Syntax
summary <model_name>
Examples
The following example inspects a learned LinearRegression model named errors_over_time
:
| summary errors_over_time
listmodels command
Use the listmodels
command to return a list of machine learning models that were learned using the fit
command. The algorithm and arguments given when fit
was invoked are displayed for each model.
Syntax
listmodels
Example
The following example lists all models:
| listmodels
deletemodel command
Use the deletemodel
command to delete a machine learning model learned using the fit
command.
The deletemodel
command modifies the model. The command is considered risky because running it can cause performance issues. As a result, this command triggers SPL safeguards. To learn more, see
Search commands for machine learning safeguards.
Syntax
deletemodel <model_name>
Example
The following example deletes the model named errors_over_time
:
| deletemodel errors_over_time
sample command
Use the sample
command to randomly sample or partition events. The command samples in one of the following three modes:
ratio
: Returns an event with the given probabilitycount
: Returns exactly that number of eventsproportional
: Samples each event with probability specified by a field value
A fourth mode of partitioning randomly divides events into a given number of partitions.
Refer to the following table for more details on the sample
command modes and additional options:
Mode or option | Name | Description |
---|---|---|
Sampling mode | ratio
|
A float between 0 and 1 indicating the probability as a percentage that each event has of being included in the result set. For example, a ratio of 0.01 means that events have a 1% probability of being included in the results. Use ratio when you want an approximation. |
count
|
A number that indicates the exact number of randomly-chosen events to return. If the sample count exceeds the total number of events in the search, all events are returned. | |
proportional
|
The name of a numeric field to use to determine the sampling probability of each event, which yields a biased sampling. Each event is sampled with a probability specified by this field value. | |
Partitioning mode | partitions
|
Use partitions to specify the number of partitions in which to randomly divide events, approximately split. Use partitions when you want to divide your results into groups for different purposes, such as using results for testing and training.
|
Additional option | seed
|
A number that specifies a random seed. Using seed ensures reproducible results. If unspecified, a pseudorandom value is used.
|
count by <field>
|
Specifies a field by which to split events, returning the count number of events for each value of the specified field. If there are more events than count , all events are included in the results.
| |
inverse
|
Use with proportional sampling. Inverts the probability, returning samples with one minus the probability specified in the proportional field
| |
fieldname
|
The name of the field in which to store the partition number. Defaults to partition_number .
|
This sample
command is not identical to using sampling options on the Event Sampling menu on the Search page in Splunk Web:
- Options from the Event Sampling menu perform sampling before the data is collected from indexes, at the beginning of the search pipeline.
- The
sample
command is applied after data is collected, accessing everything in the search pipeline.
Using the Event Sampling menu option is faster, but the sample
command is usable anywhere in the search command and provides several modes that are not available to the Event Sampling feature. For example, the sample
command supports partitioning, biased sampling, and the ability to retrieve an exact number of results.
Syntax
sample [ratio=<float between 0 and 1>] [count=<positive integer>] [proportional=<name of numeric field> [inverse]] [partitions=<natural number greater than 1> [fieldname=<string>]] [seed=<number>] [by <split_by_field>]
Examples
The following example uses the ratio
keyword and retrieves approximately 1% of all events at random:
... | sample ratio=0.01
The following example uses the count
keyword and retrieves exactly 20 events at random:
... | sample count=20
The following example uses the count
keyword and retrieves exactly 20 events at random from each host:
... | sample count=20 by host
The following example uses the proportional
keyword and returns each event with a probability determined by the value of some_field
:
... | sample proportional="some_field"
The following example partitions events into seven groups, with the chosen group returned in a field called partition_number
:
... | sample partitions=7 fieldname="partition_number"
score command
The score
command runs statistical tests to validate model outcomes. Use the score
command to validate models and statistical tests for any use case. Choose the scoring method best suited to your data and problem you want to solve with score
.
Syntax
The first argument for the scoring method is required. The options following the scoring method vary depending on the scoring method chosen.
Some scoring methods support pairwise comparisons between two sets of fields:
... | score <scoring-method-name> a_field_1 a_field_2 ... a_field_n against b_field_1 b_field_2 … b_field_m
Some scoring methods support pairwise comparisons between two sets of arrays:
... | score <scoring-method-name> array_a against array_b [options]
Some scoring methods are specific to the evaluation of clustering models:
... | score <scoring-method-name> <label_field> against <feature_field_1> ... <feature_field_n> metric=<options>
Example
The following example uses the score
command on test data:
... | score confusion_matrix true="species" pred="predicted(species)"
MLTK includes the following classes of the score
command, each with their own sets of methods:
- Classification
- Clustering scoring
- Pairwise distances scoring
- Regression scoring
- Statistical functions (statsfunctions)
- Statistical testing (statstest)
Score commands are not customizable within the Splunk Machine Learning Toolkit.
MLTK can also help you test for model overfitting using the K-fold scoring option. For more information, see K-fold scoring.
Experiment Assistants overview | Search commands for machine learning permissions |
This documentation applies to the following versions of Splunk® Machine Learning Toolkit: 5.4.0, 5.4.1, 5.4.2, 5.5.0
Feedback submitted, thanks!