Splunk Topology V2

StackState Self-hosted v5.0.x

This page describes StackState version 5.0.

Go to the documentation for the latest StackState release.

This page describes the Splunk Topology V2 integration with StackState Agent V2.

If you are currently running a Splunk Topology V1 integration using StackState Agent V1: See the instructions on how to configure the Splunk Topology V1 check or upgrade your integration to use StackState Agent V2.

Overview

When the Splunk StackPack has been installed in StackState, you can configure the Splunk Topology V2 check on StackState Agent V2 to begin collecting Splunk topology data.

The StackState Splunk Topology V2 integration collects topology from Splunk by executing Splunk saved searches from StackState Agent V2. In order to receive Splunk topology data in StackState, configuration needs to be added to both Splunk and StackState Agent V2:

• In Splunk - there should be at least one saved search that generates the topology data you want to retrieve.

• In StackState Agent V2 - a Splunk topology check should be configured to connect to your Splunk instance and execute the relevant Splunk saved searches.

The Splunk topology check on StackState Agent V2 will execute all configured Splunk saved searches periodically to retrieve a snapshot of the topology at the current time.

Splunk saved search

In the Splunk Topology V2 integration, StackState Agent V2 executes the Splunk saved searches configured in the Splunk Topology V2 Agent check and pushes retrieved data to StackState as components and relations. The fields from the results of a saved search that are sent to StackState are described below.

Topology components

The following fields from the results of a saved search are sent to StackState for topology components:

Field	Type	Required?	Description
id	string	✅	The unique identifier for the component.
name	string	✅	The value will be used as the component name.
type	string	✅	The type of component or relation.
labels	multivalue field or comma separated string	-	The values will be added as labels on the component.
identifiers	multivalue field or comma separated string	-	The values will be included as identifiers of the component.
All other fields	-	-	Splunk default fields (docs.splunk.com) other than _time will be filtered out of the result. Any other fields present in the result will be available in StackState in the data field of the properties source tab for a component.

Example query for components

Splunk query for components

| datamodel uberAgent60m System_MachineInventory search 
| dedup host 
| eval id = upper(host) | strcat "urn:host:/" id identifier
| eval name = 'id'
| eval type="host" 
| eval domain="uberAgent" 
| eval layer="Machines" 
| eval labels=split("uberAgent", ",") 
| eval identifiers=mvappend(identifier, id)
| table id type name domain layer labels identifiers

The example Splunk saved search above would result in the following topology component data in StackState:

Field	Data
id	Splunk id field.
name	Splunk name field.
type	Splunk type field.
labels	Splunk labels field
identifiers	Splunk identifiers field.
data	Splunk fields domain and layer.

Topology relations

The following fields from the results of a saved search are sent to StackState for topology relations:

Field		Type	Required?	Description
type	string	✅	The type of component or relation.
sourceId	string	✅	The ID of the component that is the source of the relation.
targetId	string	✅	The ID of the component that is the target of the relation.

Example query for relations

Splunk query for relations

| datamodel uberAgent60m Application_ApplicationInventory search 
| rename Application_ApplicationInventory.DisplayName as appname 
| table host appname | uniq 
| eval host_id = upper(host) | strcat "urn:host:/" host_id targetId 
| eval app_id = upper(appname) | rex mode=sed field=app_id "s/ /_/g" 
| strcat "urn:application:/" app_id sourceId 
| eval type="runs_on" 
| table type sourceId targetId | dedup sourceId targetId

The example Splunk saved search above would result in the following topology relation data in StackState:

Field	Data
type	Splunk type field.
sourceId	Splunk sourceId field.
targetId	Splunk targetId field.

Agent check

Configure the Splunk V2 topology check

To enable the Splunk Topology V2 integration and begin collecting component and relation data from your Splunk instance, the Splunk Topology V2 check must be configured on StackState Agent V2. The check configuration provides all details required for the Agent to connect to your Splunk instance and execute a Splunk saved search.

Example Splunk topology Agent check configuration file: splunk_topology/conf.yaml.example (github.com)

To configure the Splunk topology Agent check:

1. Edit the StackState Agent V2 check configuration file: /etc/stackstate-agent/conf.d/splunk_topology.d/conf.yaml

2. 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.

   • ignore_saved_search_errors - Set to false to return an error if one of the configured saved searches does not exist. Default true.

   • tags - Optional. Can be used to apply specific tags to all reported topology in StackState.

3. Under component_saved_searches, add details of each Splunk saved search that the check should execute to retrieve components:

   • name - The name of the Splunk saved search to execute.

     • match - Regex used for selecting Splunk saved search queries. Default "comp.*" for component queries and "relation*" for relation queries.

     • 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.

     • parameters - Used in the Splunk API request. The default parameters provided make sure the Splunk saved search query refreshes. Default force_dispatch: true and dispatch.now: true.

4. Under relation_saved_searches, add details of each Splunk saved search that the check should execute to retrieve relations.

5. More advanced options can be found in the example configuration (github.com).

6. Save the configuration file.

7. Restart StackState Agent V2 to apply the configuration changes.

8. Once the Agent has restarted, wait for the Agent to collect data and send it to StackState.

Disable the Agent check

To disable the Splunk topology Agent check:

1. Remove or rename the Agent integration configuration file, for example:

    mv /etc/stackstate-agent/conf.d/splunk_topology.d/conf.yaml /etc/stackstate-agent/conf.d/splunk_topology.d/conf.yaml.bak

2. Restart StackState Agent V2 to apply the configuration changes.

See also

• StackState Agent V2

• StackState Splunk integration details

• Splunk Topology V1 - Agent V1

• Example Splunk Topology V2 configuration file - splunk_topology/conf.yaml.example (github.com)

• Splunk default fields (docs.splunk.com)