Splunk events
StackState Self-hosted v4.5.x
This page describes StackState v4.5.x. The StackState 4.5 version range is End of Life (EOL) and no longer supported. We encourage customers still running the 4.5 version range to upgrade to a more recent release.
Overview
The StackState Splunk integration collects events from Splunk by executing Splunk saved searches that have been specified in the StackState Agent V1 Splunk events check configuration. In order to receive Splunk events data in StackState, you will therefore need to add configuration to both Splunk and StackState Agent V1.
In Splunk, there should be at least one saved search that generates the events data you want to retrieve.
In StackState Agent V1, a Splunk events check should be configured to connect to your Splunk instance and execute the relevant Splunk saved searches.
The Splunk events check on StackState Agent V1 will execute all configured Splunk saved searches periodically. Data will be requested from the last received event timestamp up until now.
Splunk is a StackState core integration.
Splunk saved search
Fields used
StackState Agent V1 executes the Splunk saved searches configured in the Splunk events Agent check configuration file and pushes retrieved data to StackState as a telemetry stream. The following fields from the results of a saved search are sent to StackState:
_time
long
✅
The data collection timestamp, in milliseconds since epoch.
event_type
string
-
Event type, for example server_created
.
msg_title
string
-
Message title.
msg_text
string
-
Message text.
source_type_name
string
-
Source type name.
All other fields
-
-
Example Splunk query
The example Splunk saved search above would result in the following event data in StackState:
_time
Splunk _time
field.
event_type
-
msg_title
-
msg_text
-
source_type_name
-
tags
hostname:<hostname>
status:<status>
description:<description>
Agent check
Configure the Splunk events check
To enable the Splunk events integration and begin collecting events data from your Splunk instance, the Splunk events check must be configured on StackState Agent V1. The check configuration provides all details required for the Agent to connect to your Splunk instance and execute a Splunk saved search.
Example Splunk events Agent check configuration file: splunk_event/conf.yaml.example (github.com)
To configure the Splunk events Agent check:
Edit the StackState Agent V1 configuration file
/etc/sts-agent/conf.d/splunk_events.yaml
.Under instances, add details of your Splunk instance:
url - The URL of your Splunk instance.
authentication - How the Agent should authenticate with your Splunk instance. Choose either token-based (recommended) or basic authentication. For details, see authentication configuration details.
tags - Optional. Can be used to apply specific tags to all reported events in StackState.
Under saved_searches, add details of each Splunk saved search that the check should execute:
name - The name of the Splunk saved search to execute.
match - Regex used for selecting Splunk saved search queries. Default
"events.*"
.app - The Splunk app in which the saved searches are located. Default
"search"
.request_timeout_seconds - Default
10
.search_max_retry_count - Default
5
.search_seconds_between_retries - Default
1
.batch_size - Default
1000
.initial_history_time_seconds - Default
0
.max_restart_history_seconds - Default
86400
.max_query_chunk_seconds - Default
3600
.unique_key_fields - The fields to use to uniquely identify a record. Default
_bkt
and_cd
.parameters - Used in the Splunk API request. The default parameters provided make sure the Splunk saved search query refreshes. Default
force_dispatch: true
anddispatch.now: true
.
More advanced options can be found in the example configuration (github.com).
Save the configuration file.
Restart StackState Agent V1 to apply the configuration changes.
Once the Agent has restarted, wait for the Agent to collect data and send it to StackState.
Events retrieved from splunk are available in StackState as a log telemetry stream in the
stackstate-generic-events
data source. This can be mapped to associated components.
Uniquely identify a record
To prevent sending duplicate events over multiple check runs, received saved search records must be uniquely identified for comparison. By default, a record is identified by the Splunk default fields _bkt
and _cd
. This behavior can be customized for each saved search by specifying unique_key_fields
in the Splunk events Agent check configuration. Note that the specified unique_key_fields
fields are mandatory fields for each record returned by the Splunk saved search.
If it is not possible to uniquely identify a record by a combination of specific fields, the whole record can be used by setting unique_key_fields: []
(an empty list).
Disable the Agent check
To disable the Splunk events Agent check:
Remove or rename the Agent integration configuration file, for example:
Restart the StackState Agent(s) to apply the configuration changes.
Splunk events in StackState
Events retrieved from splunk are available in StackState as a log telemetry stream in the stackstate-generic-events
data source. This can be mapped to associated components.
See also
Last updated