Splunk® IT Service Intelligence

REST API Reference

Download manual as PDF

This documentation does not apply to the most recent version of ITSI. Click here for the latest version.
Download topic as PDF

ITSI REST API schema

The ITSI REST API schema describes the JSON-based data structures of ITSI objects. Use this schema with the ITSI REST API to create API requests and interpret API responses. See ITSI REST API reference.

General details

ITSI backend store

ITSI stores its configuration in the KV store. KV store collections for ITSI are located at

https://<splunk_server>:8089/servicesNS/nobody/SA-ITOA/storage/collections/

Do not make any updates through the ITSI KV store collections endpoint above. Perform all operations using the REST endpoints documented in the ITSI REST API reference.

For more information about the KV store, see App Key Value Store on the Splunk developer portal.

ITSI object types

The ITSI REST API supports these object types:

  • entity
  • service
  • base_service_template (service template)
  • deep_dive
  • glass_table
  • home_view (service analyzer)
  • kpi_template
  • kpi_threshold_template
  • kpi_base_search
  • event_management_state
  • notable_event
  • notable_event_group
  • notable_event_comment
  • notable_event_aggregation_policy
  • correlation_search
  • maintenance_calendar
  • team

Note: The /SA-ITOA/<interface_category>/get_supported_object_types GET operation returns a list of currently supported object types. Note that although the entity_relationship and entity_relationship_rule objects are returned, these are not used at this time. For more information, see the ITSI REST API reference.

Common Attributes

The following attributes are common to all ITSI objects. These attributes are available in the model for each object type.

Field Type Description
object_type String Name of object type.
create_by String User who created this object.
create_source String Source type initiating create. Has value "manual" for user initiated creates. For internal use only.
create_time String Timestamp at create based on UTC time zone.
mod_source String Source type initiating modification. Has value "manual" for user initiated modificaitons. For internal use only.
mod_time String Timestamp of last modification based on UTC time zone.
_owner String Splunk user "nobody".
_user String User who performed latest operation on this object.
version Number version of the object. Currently the same as the ITSI app version.

Note: Common attributes are elided from the object schemas below to make the documentation easier to read.

Entity

Description

An entity is a basic unit of configuration in an IT environment that meets a specific need for an IT service. Entities are usually servers, but can be other IT infrastructure components, such as network devices, storage subsystems, applications, and so on. Entities are optional.

The entity object contains field aliases and values that identify the entity in KPI searches.

Attributes

Field Type Description
_key String Auto-generated unique identifier for this entity.
title String Name of the entity.
description String User defined description of the entity.
object_type String entity
identifier Object values: Array of alias values that identify the entity
fields: Array of search fields that identify events for the entity.
informational Object values: Array of alias values that provide information/description for the entity.
fields: Array of search fields to extract information/description of the entity.
services Array Array of sub-objects with _key and title fields of services monitoring this entity via rules configured in services.
sec_grp String The team the object belongs to. The entity object can only belong to default_itsi_security_group (Global team).
sai_entity_key String This field exists in ITSI entities that have been merged with SAI entities. It symbolizes the original SAI entities's _key and is used for drilldowns to SAI.

Note: _key and title attributes can be any unique value.

For more information, see Entity in the ITSI Installation and Configuration Manual.

Service

Description

An ITSI service is a representation of a real world IT service. You can configure an ITSI service to monitor various IT metrics using KPI searches, which reflect the health of a service. ITSI services can describe any real world IT service, such as a network service or email service.

The service object contains the service definition, including entities, KPIs, and dependent services.

Attributes

Field Type Description
_key String Auto-generated unique identifier for this service.
description String User defined description for the service.
title String Title of this service.
kpis Array Array of KPI descriptions for this service.
entity_rules Array Array of rules describing entities referenced by this service.
services_depends_on Array Array of service descriptions with KPIs in those services that this service depends on.
service_id String _key value of service that this service depends on.
kpis_depending_on Array Array of _key ids for each KPI in service identified by serviceid, which this service will depend on.
services_depending_on_me Array An array of service descriptions with KPIs in this service that those services depend on.
serviceid String _key value of service that depends on this service.
kpis_depending_on Array Array of of _key ids of each KPI in this service, which the service identified by serviceid will depend on.
Enabled Boolean If set to 1, service is enabled. If value is absent or not set to 1, service is disabled. On upgrade service is flagged as enabled.
sec_grp String The team the object belongs to.
base_service_template_id String The ID of the service template the service is linked to. Not required. If empty, the service is not linked to a service template. To create a service based on a service template, include this field.

For more information, see Services in the ITSI Installation and Configuration Manual.

Subordinate objects

Service template

Description

ITSI service templates enable you to manage shared content for similar services. Services linked to a service template receive content from the service template, such as KPIs and entity rules. You must create a service template from an existing service.

Attributes

Field Type Description
_key String Auto-generated unique identifier for this service template.
description String User defined description for the service template.
title String Title of this service template.
kpis Array Array of KPI descriptions for this service template.
entity_rules Array Array of rules describing entities referenced by this service template.
service_id String _key value of the service this service template is generated from.
sec_grp String The team the service template belongs to. Service templates can only belong to default_itsi_security_group (Global team).
linked_services Array Array of services linked to this service template. if the user does not have access to all linked services, the linked_services field only contains the services they have read access to.
total_linked_services Number The number of services linked to this service template.
last_sync_error String Error message if the last sync operation failed.
sync_status String Sync status of service template: "synced", "sync_scheduled", "syncing", "sync failed".
scheduled_time Number The time to push service template changes to linked services if "sync later" is selected rather than "sync now".
scheduled_job Dict Sync job detail if "sync later" is selected rather than "sync now".

Subordinate objects

Entity Rules

Description

entity_rules determine the specific entities that a KPI monitors in a service. This includes entities directly identified by title, and entities identified by regular expression-based rules.

Attributes

Entity rules are an array of rule groups which are ORed at the top level.

Field Type Description
rule_condition Boolean operator Uses the value AND indicating this rule ANDs all nested rules contained in rule_items.
rule_items Array Array of rules that are ANDed within a rule group.
field String The field in the entity definition to compare values to evaluate this rule.
rule_type String Takes values "not" or "matches" to indicate if this is an inclusion or exclusion rule. Value can be "matchesblank" or "doesnotmatchblank" when used with service templates.
value String Values to evaluate in the rule. To specify multiple values, separate them with a comma. Values are not case sensitive.
field_type String Takes values "alias" or "info" specifying in which category of fields the "field" attribute is located.

Entity rules evaluation samples

The following samples show how ITSI evaluates entity_rules.

Match all entities that are a given title value like "Foo"
  
"entity_rules": 
[
    {
       "rule_condition": "AND",
       "rule_items": 
        [
            {
                "field": "title",
                "rule_type": "matches",
                "value": "Foo",
                "field_type": "title"    
            }
        ]
    }
]
Match all entities that are a given alias field named category value pattern like "*Foo*"
  
"entity_rules": 
[
    {
       "rule_condition": "AND",
       "rule_items": 
        [
            {
                "field": "category",
                "rule_type": "matches",
                "value": "*Foo*",
                "field_type": "alias"    
            }
        ]
    }
]
Exclude all entities that are a given info field named subcategory value like "Foo"
 
 
"entity_rules":
[
    {
       "rule_condition": "AND",
       "rule_items":
        [
            {
                "field": "subcategory",
                "rule_type": "not",
                "value": "Foo",
                "field_type": "info"   
            }
        ]
    }
 
]
Exclude all entities that are a given title value pattern like "*Foo*"
 
"entity_rules":
[
    {
       "rule_condition": "AND",
       "rule_items":
        [
            {
                "field": "title",
                "rule_type": "not",
                "value": "*Foo*",
                "field_type": "title"   
            }
        ]
    }
 
]
Match all entities that are a given info field named subcategory value like "Foo" AND also are a given alias field named category value pattern like "*Bar*"
OR
Match all entities that are one of the given title value and value pattern namely "Title1", "*Title2*" or "Title3"
 
"entity_rules":
[
    {
       "rule_condition": "AND",
       "rule_items":
        [
            {
                "field": "category",
                "rule_type": "matches",
                "value": "*Bar*",
                "field_type": "alias"   
            },
            {
                "field": "subcategory",
                "rule_type": "matches",
                "value": "Foo",
                "field_type": "info"   
            }
        ]
    },
    {
       "rule_condition": "AND",
       "rule_items":
        [
            {
                "field": "title",
                "rule_type": "matches",
                "value": "Title1,*title2*,Title3",
                "field_type": "title"   
            }
        ]
    }
]

Service KPI

Description

KPI is the data structure that drives the monitoring of service metrics. Each KPI object contains specific information, including a user-configured base search, from which ITSI generates the search that monitors a metric. KPI objects also contain information on how to apply thresholds that determine the metric severity level.

KPI objects (kpis) are defined and contained within the service object type data structure.

Attributes

Field Type Description
_key String Auto-generated unique ID for this KPI.
title String User-defined name for the KPI
description String User-defined description for the KPI.
type String kpi_primary
kpi_template_kpi_id String User-defined ID for the KPI. Used to refer to KPIs within a KPI template in modules. This uniquely identifies a KPI template in ITSI.
isadhoc Boolean If true the search is split on entities and thresholds are computed for both entity and aggregate.
is_service_entity_filter Boolean If true a filter is used on the search based on the entities included in the service.
datamode String The data model to use for search generation if this is a data model type search.
datamodel_filter String ITSI generated clauses for user-defined filters on top of the datamodel fields. Used in the KPI search to filter events required by this KPI.
threshold_field String User-specified field on which statistical operations are performed and whose value determines KPI health.
entity_statop String Statistical operation (avg, max, mean, and so on) used to combine data for alert_values on a per entity basis (used if entity_breakdown is true).
aggregate_statop String Statistical operation (avg, max, median, stdev, and so on) used to combine data for the aggregate alert_value (used for all KPI).
urgency Number User-assigned importance value for this KPI.
unit String User-defined units for the values in threshold field.
entity_id_fields String Fields from this KPI's search events that will be mapped to the alias fields defined in entities for the service containing this KPI. This field enables the KPI search to tie the aliases of entities to the fields from the KPI events in identifying entities at search time.
entity_alias_filtering_fields String Subset of aliases from all entities included in the service containing this KPI, to restrict this KPI to only the subset of entities matching via the subset of aliases. Helps filter entities for this KPI among the ones selected in the service containing this KPI.
cron_schedule String The cron schedule that determines the frequency of this KPI search.
base_search String KPI search defined by user for this KPI. All generated searches for the KPI are based on this search.
kpi_base_search String A basic search generated for the KPI search.
search String Generated search for this KPI for base statistics on the threshold field.
search_entities String Generated search for this KPI for base statistics on the threshold field to use for "Per Entity" threshold type.
search_aggregate String Generated search for this KPI for base statistics on the threshold field to use for "Aggregate" or "Both" threshold type.
search_time_series String Generated search used primarily to show preview information in the KPI configuration page.
search_time_series_entities String Generated search used primarily to show preview information for "Per Entity" threshold type in the KPI configuration page
search_time_series_aggregate String Generated search used primarily to show preview information for "Aggregate" or "Both" threshold type in the KPI configuration page.
search_time_compare String Generated search used specifically by glass table.
search_alert String Generated search used for alerting based on KPI threshold. This is the search that runs on schedule via the saved search for this KPI.
search_alert_entities String Generated search to use for alerting based on KPI threshold for "Per Entity" threshold type.
search_alert_entities String Generated search to use for alerting based on KPI threshold for "Aggregate" or "Both" threshold type.
alert_on String Specified if the threshold type for this KPI is "Per Entity" or "Aggregate" or "Both". Possible values: aggregate, entities, both.
alert_period String User specified interval to run the KPI search in minutes.
alert_lag Number Contains the number of seconds of lag to apply to the alert search, max is 30 minutes (1800 seconds)
search_alert_earliest String Earliest time to look for events every time KPI search runs. This determines how far back each time window is during KPI search runs.
tz_offset String ISO time zone offset. Note: Do not change this value.
time_variate_thresholds Boolean If true, thresholds for alerts are pulled from time_variate_thresholds_specification.
time_variate_thresholds_specification Object Data structure for time variate threshold specs.
backfill_enabled Boolean Indicates if backfill has been enabled for this KPI
backfill_earliest_time String Requested earliest time for backfill (relative time offset). Should be in the format -Xd, where 'd' means the time is in days, 'X' is number of days to backfill, and '-' means the date is in the past.
adaptive_thresholds_is_enabled Boolean Determines if adaptive threshold is enabled for this KPI.
adaptive_thresholding_training_window String Earliest time for the Adaptive Threshold training algorithm to run over (latest time is always 'now') (e.g. '-7d')
anomaly_detection_is_enabled Boolean Determines if trending anomaly detection is enabled.
cohesive_anomaly_detection_is_enabled Boolean Determines if cohesive anomaly detection is enabled.
anomaly_detection_alerting_enabled Boolean Determines if anomaly detection will alert for anomalies.
anomaly_detection_training_window String Earliest time for the training algorithm to run over (latest time is always 'now') (e.g. '-7d').
trending_ad Object Data structure for trending anomaly detection algorithm settings. See Anomaly Detection Algorithm Settings.
cohesive_ad Object Data structure for cohesive anomaly detection algorithm settings. See Anomaly Detection Algorithm Settings.
gap_severity String Severity level assigned for data gaps (info, normal, low, medium, high, critical, or unknown)
gap_severity_color String Severity color assigned for data gaps.
gap_severity_color_light String Severity color assigned for data gaps.
gap_severity_value String Severity value assigned for data gaps.
entity thresholds Object User-defined thresholding levels for "Per Entity" threshold type. For more information, see KPI Threshold Setting.
aggregate_thresholds String User-defined thresholding levels for "Aggregate" threshold type. For more information, see KPI Threshold Setting.
Enabled Boolean If set to 1, KPI is enabled. If absent or not set to 1, KPI is disabled. On upgrade KPI is flagged as enabled. Field is read-only.
base_service_template_id String The key of service template object if the KPI is inherited from a service template.
entity_breakdown_id_field String KPI search events are split by the alias field defined in entities for the service containing this KPI.

Service Template KPI

Description

KPI is the data structure that drives the monitoring of service metrics. KPI objects for service templates differ slightly from KPI objects for services. For example, service template KPIs can only use base searches (not ad hoc searches or searches based on data models) and anomaly detection cannot be enabled for service template KPIs.

KPI objects (kpis) for service templates are defined and contained within the base_service_template object type data structure.

Attributes

Field Type Description
_key String Auto-generated unique ID for this KPI.
title String User-defined name for the KPI
description String User-defined description for the KPI.
type String kpi_primary.
kpi_template_kpi_id String User-defined ID for the KPI. Used to refer to KPIs within a KPI template in ITSI modules. This uniquely identifies a KPI template in ITSI.
is_service_entity_filter Boolean If true a filter is used on the search based on the entities included in the service.
datamode String The data model to use for search generation if this is a data model type search.
datamodel_filter String ITSI generated clauses for user-defined filters on top of the data model fields. Used in the KPI search to filter events required by this KPI.
threshold_field String User-specified field on which statistical operations are performed and whose value determines KPI health.
entity_statop String Statistical operation (avg, max, mean, and so on) used to combine data for alert_values on a per entity basis (used if entity_breakdown is true).
aggregate_statop String Statistical operation (avg, max, median, stdev, and so on) used to combine data for the aggregate alert_value (used for all KPI).
urgency Number User-assigned importance value for this KPI.
unit String User-defined units for the values in threshold field.
entity_id_fields String Fields from this KPI's search events that will be mapped to the alias fields defined in entities for the service containing this KPI. This field enables the KPI search to tie the aliases of entities to the fields from the KPI events in identifying entities at search time.
entity_alias_filtering_fields String Subset of aliases from all entities included in the service containing this KPI, to restrict this KPI to only the subset of entities matching via the subset of aliases. Helps filter entities for this KPI among the ones selected in the service containing this KPI.
cron_schedule String The cron schedule that determines the frequency of this KPI search.
base_search String KPI search defined by user for this KPI. All generated searches for the KPI are based on this search.
kpi_base_search String A basic search generated for the KPI search.
alert_on String Specified if the threshold type for this KPI is "Per Entity" or "Aggregate" or "Both". Possible values: aggregate, entities, both.
alert_period String User specified interval to run the KPI search in minutes.
alert_lag Number Contains the number of seconds of lag to apply to the alert search, max is 30 minutes (1800 seconds)
search_alert_earliest String Earliest time to look for events every time KPI search runs. This determines how far back each time window is during KPI search runs.
tz_offset String ISO time zone offset. Note: Do not change this value.
time_variate_thresholds Boolean If true, thresholds for alerts are pulled from time_variate_thresholds_specification.
time_variate_thresholds_specification Object Data structure for time variate threshold specs.
adaptive_thresholds_is_enabled Boolean Determines if adaptive threshold is enabled for this KPI.
adaptive_thresholding_training_window String Earliest time for the Adaptive Threshold training algorithm to run over (latest time is always 'now') (e.g. '-7d')
gap_severity String Severity level assigned for data gaps (info, normal, low, medium, high, critical, or unknown)
gap_severity_color String Severity color assigned for data gaps.
gap_severity_color_light String Severity color assigned for data gaps.
gap_severity_value String Severity value assigned for data gaps.
entity thresholds Object User-defined thresholding levels for "Per Entity" threshold type. For more information, see KPI Threshold Setting.
aggregate_thresholds String User-defined thresholding levels for "Aggregate" threshold type. For more information, see KPI Threshold Setting.
Enabled Boolean If set to 1, KPI is enabled. If absent or not set to 1, KPI is disabled. On upgrade KPI is flagged as enabled. Field is read-only.
entity_breakdown_id_field String KPI search events are split by the alias field defined in entities for the service containing this KPI.

Service Health KPI

The Service Health KPI tracks the health score of an entire service. Service Health KPIs have the same data structure as user defined KPIs.

Service Health KPIs have the following ID format:

SHKPI-<_key id for the service>

Subordinate objects

KPI Threshold Settings

Description

KPI Threshold Settings define the thresholds that a KPI uses to compute health status information. KPI Threshold Settings also contain information for rendering KPI threshold graphs.

Attributes

Field Type Description
gaugeMin Number Minimum value for the threshold gauge specified by user.
gaugeMax Number Maximum value for the threshold gauge specified by user.
search String Generated search used to compute the thresholds for this KPI.
baseSeverityValue Number Value for base threshold level.
baseSeverityColor String Severity color assigned for the base threshold level.
baseSeverityColorLight String Severity light color assigned for the base threshold level.
baseSeverityLabel String Severity label assigned for the base threshold level, including info, warning, critical, etc.
metricField String Thresholding field from the search.
renderBoundaryMin Number Lower bound value to use to render the graph for the thresholds.
renderBoundaryMax Number Upper bound value to use to render the graph for the thresholds.
isMaxStatic Boolean True when maximum threshold value is a static value, false otherwise.
isMinStatic Boolean True when min threshold value is a static value, false otherwise.

Subordinate data structures

KPI Threshold Levels

Description

KPI Threshold Levels determine how ITSI extracts health status information from KPI searches. Threshold levels are user-configured values that can be augmented further using adaptive thresholding.

Attributes

Field Type Description
thresholdValue Number Value for the threshold field stats identifying this threshold level. This is the key value that defines the levels for values derived from the KPI search metrics.
severityColor String Severity color assigned for this threshold level.
severityColorLight String Severity light color assigned for this threshold level.
severityValue Number Severity value assigned for this threshold level.
severityLabel String Severity label assigned for this threshold level like info, warning, critical, etc.
dynamicParam Number Value of the dynamic parameter for adaptive thresholds.

KPI Threshold Templates

Description

A KPI Threshold Template is a set of pre-defined threshold values that you can apply to multiple KPIs.

Attributes

Field Type Description
title String Name of this template.
description String Description of this particular template.
adaptive_thresholding_training_window String Earliest time for the AT training algorithm to run over (latest time is always 'now').
time_variate_thresholds Boolean If true, thresholds for alerts are pulled from time_variate_thresholds_specification.
Time_variate_thresholds_specification Object Data structure for time variate threshold specification.
adaptive_thresholds_is_enabled Boolean If true, adaptive thresholding is enabled for this KPI.
sec_grp String The team the object belongs to. This object can only belong to default_itsi_security_group (Global team).

KPI Base Search

Description

Searches that can be aggregated together to reduce overall search load. KPI Base Searches include the core attributes of a KPI for search generation.

kpi_base_search objects are contained within the KPI (kpis) object data structure.

Attributes

Field Type Description
entity_alias_filtering_fields String The fields to filter on. See KPI definition.
_version String ITSI version number of this KPI base search.
description String General description for this KPI base search.
mod_source String Source of the last modification.
mod_time String The time of the last modification based on UTC time zone.
is_service_entity_filter Boolean If true a filter is used on the search based on the entities included in the service.
actions String
object_type String kpi_base_search
is_entity_breakdown String Determines if search breaks down by entities. See KPI definition.
_owner String KV store owner.
source_itsi_da String Source of DA used for this search. See KPI Threshold Templates.
metrics Array Set of statistical operations performed on threshold field.
aggregate_statop String Statistical operation (avg, max, median, stdev, and so on) used to combine data for the aggregate alert_value (used for all KPI).
unit String User-defined units for the values in threshold field.
title String Name of this metric
_key String Internal identifier.
threshold_field String The field on which the statistical operation runs.
entity_statop String Statistical operation (avg, max, mean, and so on) used to combine data for alert_values on a per entity basis (used if is_entity_breakdown is true).
search_alert_earliest String Earliest time to look for events every time KPI search runs. This determines how far back each time window is during KPI search runs.
alert_period String User specified interval to run the KPI search in minutes.
alert_lag String Contains the number of seconds of lag to apply to the alert search, max is 30 minutes (1800 seconds).
base_search String KPI search defined by user for this KPI. All generated searches for the KPI are based on this search.
entity_id_fields String Fields from this KPI's search events that will be mapped to the alias fields defined in entities for the service containing this KPI. This field enables the KPI search to tie the aliases of entities to the fields from the KPI events in identifying entities at search time.
identifying_name String Internal only
title String Name of this KPI base search.
mod_timestamp String Timestamp of last modification based on UTC time zone.
acl String Access control blob.
_user String Like owner, but different.
_key String Auto-generated unique ID for this KPI.
sec_grp String The team the object belongs to. This object can only belong to default_itsi_security_group (Global team).

For more information, see Create a KPI base search in the ITSI Installation and Configuration Manual.

Glass Table

Description

ITSI glass tables are custom visualizations that let you monitor KPI search results.

glass_table objects define all widgets and drawing elements that appear in the glass table.

Attributes

Field Type Description
_key String Unique identifier for this glass table.
title String Name of this glass table.
description String User-defined description for this glass table.
object_type String glass_table.
latest String Latest time for all of the widget searches on the glass table.
latest_label String Latest label displayed in the glass table instant picker. Matches latest attribute.
svg_coordinates String x and y viewbox offsets for the glass table.
content Array Array of JSON structures containing all attributes needed to draw the glass table. See Glass Table Widget Configuration.
is_epoch Boolean True when the glass table uses a custom (non-preset) time, false otherwise.
templateSelectedServiceId String The id of the service currently in focus if templatization is enabled.
templateSwappableServiceIds Array The array of services available to be swapped to for templatization.

Subordinate data structures

Glass Table Widget Configuration

Description

Glass Table Widget Configuration (content) is an array of JSON structures that contains all of the attributes needed to render the glass table. Each element of the array represents one glass table widget, and the attributes of the element are parsed into a glass table BaseWidgetViewManager object.

Attributes

Field Type Description
search String The search to power the widget.
labelVal String The text to show in the label located beneath the widget.
labelFlag Boolean True if labelVal is to be shown with the widget, false otherwise.
vizType Number Numeric indication of which viz type the widget is - SingleValue, Gauge, Sparkline, SVD from 0-3, respectively
threshold_field String Field in data to which thresholds apply.
threshold_comparator String Comparator used for threshold severity computation
threshold_values Array Array of values to indicate the bounds of the thresholds set for the widget.
threshold_labels Array Array of labels to match the threshold values set for the widget.
context_id String Id of service to which the widget's KPI belongs.
kpi_id String Id of KPI the widget represents
searchSource String Source of search for glass table widget - can be datamodel or ad hoc.
dataModelSpecification String Data model specification for the datamodel search.
dataModelStatOp String Datamodel stats operation for the datamodel search.
dataModelWhereClause String Datamodel where clause for the datamodel search.
threshold_eval String Threshold eval search clause for threshold severity evaluation.
aggregate_eval String Aggregate eval search clause for threshold severity evaluation.
base_search String Base search of the KPI the widget represents.
search_alert_earliest String Earliest time for the search that powers the widget.
entities String List of entities that the widget's KPI contains.
search_aggregate String Aggregate search of the KPI the widget represents.
search_time_series_aggregate String Time series search of the KPI the widget represents
search_time_compare String Compare time series search of the KPI the widget represents (for the SVD viz type).
search_type String Type of search the widget is powered by. Must match one of the search_* attributes of the widget.
relativeEarliest String Earliest time (in relative units) for the search that powers the widget.
defaultWidth Number Initial width to use for the widget.
defaultHeight Number Initial height to use for the widget.
existingKPI Boolean True if KPI exists in user's system, false otherwise.
alert_on String Threshold alert type (aggregate or entities) of the KPI the widget represents.
isThresholdEnabled Boolean True if thresholds should be applied to the widget's search results, false otherwise.
useKPISummary Boolean true if widget uses the kpi_summary_index to power its search, false otherwise.
unit String Unit string for widget to display.
gap_severity String Gap severity value of the KPI the widget represents.
gap_severity_color String Gap severity color of the KPI the widget represents.
drilldownSettingsModel String Model to hold properties required for generating URLs for custom drilldown.
useCustomDrilldown Boolean True if widget has custom drilldown turned on, false otherwise.

Glass Table Icon

Description

Contains SVG icon definitions and metadata for glass table icons.

Attributes

Field Type Description
_key String Auto-generated unique identifier for this icon.
title String Name of the icon.
category String Category of the icon.
default_width Number Width of the icon.
default_height Number Height of the icon.
svg_path String SVG path defining shape of the icon.
immutable Boolean Should the REST API allow editing of this icon. False for all icons imported from .conf files.
_time String Timestamp when the icon was added.
_owner String Name of the user that added this icon.

Deep Dive

Description

ITSI deep dives are investigative tools that help you identify and troubleshoot issues in your IT environment. You can use deep dives to view KPI search results over time, zoom-in on KPI metrics and log events, and visually correlate root cause. You can add different types of lanes to a deep dive view, including KPI lanes, which let you view KPI metrics in detail. You can also add lanes to view ad hoc and data model searches.

deep_dive objects contain all of the elements required to render deep dive lanes.

Attributes

Field Type Description
_key String Auto-generated unique identifier for this deep dive.
description String User-defined description for this deep dive.
title String Name of the deep dive.
object_type String deep_dive
earliest_time String Earliest time for all of the searches in this deep dive.
latest_time String Latest time for all of the searches in this deep dive.
focus_id String The service id of the service in focus.
topology_id String Define the service to be put in focus in the deep dive topology view. If none exists then the focus_id is set as the topology_id. view sidebar
lane_settings_collection Array <Array of lane settings specifying each lane's configuration. See Deep Dive Lane Settings.
is_named Boolean True when the deep dive is saved, false otherwise.

Subordinate data structures

Deep Dive Lane Setting

Description

Configuration settings that define what information a deep dive lane shows. Deep dive views use these settings for per lane configuration.

Attributes

Field Type Description
title String Name of the lane to display.
subtitle String The subtitle of the lane to display.
laneType String The type of lane to render. Possible values: event, kpi, metric (the default).
graphType String The type of graph to render
search String The search to use to get data for the lane.
searchSource String Represents how a search is generated. Possible values: datamodel, ad hoc search, or kpi search.
dataModelSpecification Object An object showing the selections that went into the generation of the search, null unless searchSource is data model. If defined, it is structured as {datamodel: object: <Object Name>, field: <Field Info Data Structure>.
dataModelStatOp String Stats operation used in the data model search.
dataModelWhereClause String Where clause defined during data model search creation.
overwriteKpiTitle String Overwrite KPI title with user specified title.
overwriteEntityTitle String Overwrite Entity title with user specified title.
kpiTitle String The original title of the KPI as defined in the KPI model.
kpiServiceId String The id of the service associated with the selected KPI.
kpiUnit String The unit of the KPI driving this lane.
kpiAddToSummary String Add or remove from kpi summary based on user selection. [yes, no] Yes runs the search against kpi summary index and no runs raw search.
kpiStatsOp String Stats operation to calculate the KPI value, avg by default [avg, max, min, median].
entityAddToSummary String Shows the accelerated output for entity lanes. Always set to "yes."
thresholdIndicationEnabled String Enable/disable threshold indication. Disabled by default.
thresholdIndicationType String Type of threshold indication. [foreground/background] Foreground selected by default.
hideGraph String Only available with background threshold indications. If selected, hides the graph and only shows the top view with background thresholds [yes, no].
verticalAxisScale String Determines the scale of the y axis. It is linear or log.
verticalAxisBoundaryType String Determine the extent of the y axis. It is staticValue, value, or zeroValue.
verticalAxisStaticBounds Object If static, these are the bounds to use. Otherwise this is ignored. This is an object of the form[<min number>, <max number>].
dataGaps String null values in the data can be represented as gaps or connected through the graph.
graphColor String The color of the graph to render.
graphSeries String The field in the data which to plot as the range, if unspecified plots all.
excludeSeries String The series of data to omit from being displayed in graph. Series with a leading _ (indicating internal use) is always excluded.
laneOverlaySettingsModel Object Model to define the overlay lane settings.

Time Variate Thresholds Specification

Description

This data structure contains the threshold policy collection. A threshold policy includes information on which thresholds are to be applied (a threshold setting model), how those thresholds are generated, and the time periods to which the threshold policy applies. Each policy object includes a single time_blocks attribute that contains a list of time periods with which the policy is associated.

In the case of static thresholding there are no parameter attributes. In the case of dynamic thresholding, parameters are stored in a simple object within the policy.

Attributes

Field Type Description
title String The title of the threshold spec. Used when creating/modifying threshold spec templates.
description String User-defined description of the threshold specifications.
policies Object JSON object keyed by policy ID.
time_blocks Array Determines time periods with which the policy is associated.

Collection details

A threshold policy collection is accessed by the UUID key of the policy. There is no limit to the number of policies a collection can contain.

Threshold policies

{
  _key: <UUID>,
  title: <optional title>,
  aggregate_thresholds: <ThresholdSettingsModel>,
  entity_thresholds: <ThresholdSettingsModel>,
  policy_type: <ENUM of "static", "stdev", "quantile", or "range">
  time_blocks: <[] of time blocks>
}

Time blocks attribute

The time_blocks attribute uses a simplified cron expression format.

[
  ['<minute> <hour> <*> <*> <day>', <duration in minutes>] 
]

<minute> values can only be 0, 15, 30, or 45. <hour> values use 24 hour day format. Unlike standard cron expressions, <day> values run from 0 for Monday through 6 for Sunday.

For example:

'time_blocks': [
  ['15 3 * * 3,4', 60]   // 1 hour time range, 3:15AM - 4:15AM on Thurs, Fri
]

The time block attribute must specify exactly one cron expression.

If your existing configuration does not match the UTC timestamp, use the kvstore_to_json.py script to correct the time zone discrepancy. See Time zone offset operations (mode 3) in the ITSI Installation and Configuration Manual.

Usage

Generation of Time Varied Threshold lookup in custom search command

The main usage of the threshold policy structures is to determine which thresholds should be applied based on the time.

Configure adaptive threshold commands

Threshold policy structures are used to configure how the adaptive threshold commands work. They need access to the time blocks for a particular policy and the parameters in the policy. They access this information by reading the KPI and applying the information stored within.

Maintenance Calendar

Description

Use Maintenance Calendar to configure services and entities to be in maintenance mode at required intervals.

Attributes

Field Type Description
_key String Unique ID for the entry in KV store.
title String User given title for the calendar entry.
comment String Optional comment describing the entry.
objects Array Array of dictionaries describing object put in maintenance by this calendar entry.
Schema for each object definition in the array:
_key: Unique if assigned to the object currently.
object_type: Type of object being identified. Currently only "entity" and "service" are allowed.
start_time String Timestamp that marks the beginning of maintenance window. Based on UTC time zone.
end_time String Timestamp that marks the end of maintenance window. Based on UTC time zone.

If your existing configuration does not match the UTC timestamp, use the kvstore_to_json.py script to correct the time zone discrepancy. See Time zone offset operations (mode 3) in the ITSI Installation and Configuration Manual.

Event Management State

Description

The event_management_state object stores user settings for Episode Review.

Attributes

Field Type Description
_key String Unique ID for the entry in KV store.
title String User-defined name for the calendar entry.
earliest String Earliest time for main search in the Event Management console.
latest String Latest time for main search in the Event Management console.
fetchLimit Number Maximum number of notable events to fetch in a single request.
sortField String Field in data (column in Event Management console table) to sort notable events by.
sortDirection String Indicates whether to sort notable events in ascending or descending order.
arbitrarySearch String Splunk search string used to filter raw notable events.
filterCollection Array Set of filters that represent the Event Management console page filters.
viewingOption String Indicates whether to display notable events as standard or prominent in Event Management console.
eventDeduplication Boolean If true, episode view is turned on, false otherwise.
columnsShown Array List of fields in data (column in Event Management console) to show.

Notable Event Group

Description

The notable_event_group contains information about an episode.

Attributes

Field Type Description
severity String The level of importance of the episode. Values must match an integer specified in the default version of itsi_notable_event_severity.conf (or the local version if you created one). Default values:
1 - Info
2 - Normal
3 - Low
4 - Medium
5 - High
6 - Critical
status String The triage status of the episode in Episode Review. Values must match an integer specified in the default version of itsi_notable_event_status.conf (or the local version if you created one). Default values:
0 - Unassigned
1 - New
2 - In Progress
3 - Pending
4 - Resolved
5 - Closed
owner String The Splunk user who is the owner of the episode.
_key String The group ID that a change is associated with.

Notable Event Comment

Description

notable_event_comment contains comments associated with an episode.

Attributes

Field Type Description
comment String The text of the comment.
event_id String The episode ID that the comment is associated with.
is_group Boolean The episode ID that the comment is associated with.
filter_search String The search to retrieve all the comments for an episode.
earliest_time String The time in UTC of the first event in the episode.
latest_time String The time in UTC of the last event in the episode.

Notable Event Aggregation Policy

Description

notable_event_aggregation_policy contains the data for a notable event aggregation policy which aggregates notable events into episodes.

Attributes

Field Type Description
disabled Integer 1 meaning disabled or 0 meaning enabled.
breaking_criteria Object A JSON blob of all the criteria used to break a group.
filter_criteria Object A JSON blob of all the criteria used to filter events into a group.
is_default Integer Indicates if this is the default policy. 1 meaning no or 0 meaning yes.
description String The description of the notable event aggregation policy.
group_severity String The severity for each group created by the notable event aggregation policy.
group_status String The status for each group created by the notable event aggregation policy.
group_asignee String The owner for each group created by the notable event aggregation policy.
group_description String The description for each group created by the notable event aggregation policy.
title String The title of the notable event aggregation policy.
rules Array An array of all the rules and actions to be executed for the notable event aggregation policy.
split_by_field String A string containing all the fields to split groups by.

Correlation Search

Description

correlation_search contains the data for a correlation search. A correlation search is a recurring search that generates a notable event when search results meet specific conditions. A multi-KPI alert is a type of correlation search.

Attributes

Field Type Description
is_scheduled Integer Values: 1 means scheduled; 0 means not scheduled.
disabled Integer Values: 1 means disabled; 0 means enabled.
cron_schedule String Schedule searches to run periodically at fixed times, dates, or intervals using a cron expression. Default value is */5* * * * (every 5 minutes).
dispatch.earliest_time String Indicates the beginning of the time range for the search. The default value is -15m.
dispatch.latest_time String Indicates the end of the time range for the search. The default value is -now.
description String A description of the type of issue the search is intended to detect.
search String The Splunk search to run.
name String A name that describes the correlation search. For example, "cpu_load_percent".
action.itsi_event_generator.param.title String The title to use for the notable event in Episode Review. For example, mysql-01 server cpu Load %.
action.itsi_event_generator.param.description String A brief phrase to describe the notable event. For example, "This alert triggers when DB CPU load on the mysql-01 server reaches 80%."
action.itsi_event_generator.param.status String The triage status of the event in Episode Review. You can provide a token in the format %fieldname% to substitute the value of a third-party alert field. Values must match an integer specified in $SPLUNK_HOME/etc/apps/SA-ITOA/local/itsi_notable_event_status.conf or /default/itsi_notable_event_status.conf if a local version does not exist. By default, these values are 0-5.
action.itsi_event_generator.param.owner Array The ITSI role to which the notable event is assigned in Episode Review.
action.itsi_event_generator.param.severity String The level of importance of the event. You can provide a token in the format %fieldname% to substitute the value of a third-party alert field. Values must match an integer specified in $SPLUNK_HOME/etc/apps/SA-ITOA/local/itsi_notable_event_severity.conf or /default/itsi_notable_event_severity.conf if a local version does not exist. By default, these values are 1-6.
action.itsi_event_generator.param.drilldown_search_title String The name of the drilldown search link. You can drill down to a specific Splunk search from an episode in Episode Review.
action.itsi_event_generator.param.drilldown_search_search String The Splunk search you drill down to.
action.itsi_event_generator.param.drilldown_search_latest_offset String Defines how far ahead from the time of the event to look for related events.
action.itsi_event_generator.param.drilldown_search_earliest_offset String Defines how far back from the time of the event to start looking for related events.
action.itsi_event_generator.param.drilldown_title String The name of the drilldown website link if you want to drill down to a specific website from the episode in Episode Review.
action.itsi_event_generator.param.drilldown_uri String The website you drill down to.
action.itsi_event_generator.param.event_identifier_fields String These identifier fields form the event hash field, which is added to every notable event to help identify unique alarm types.
action.itsi_event_generator.param.service_ids String One or more ITSI services to which this correlation search applies. You can only specify services that belong to teams for which you have read access.
action.itsi_event_generator.param.entity_lookup_field String The field in the data retrieved by the correlation search that is used to look up corresponding entities. For example, host.
action.itsi_event_generator.param.search_type String search_type = "basic", "composite_kpi_score_type", or composite_kpi_percentage_type
action.itsi_event_generator.param.meta_data Object One of two JSON object schemas, depending on whether it is a correlation search or a multi-KPI alert.
Correlation search object schema:
  • threshold_health_score - threshold score set by user
  • threshold_status - threshold status (default is undefined)
  • suppression criteria fields
  • alert_type - score or status
  • is_suppression - if suppression is enabled or not
  • is_consecutive - if count is consecutive or not
  • count - minimum number of times if this alert happens
  • suppression_period - suppression period in minute if it is non-consecutive
  • min_alert_period - minimum alert period of selected KPIs
  • run_every - frequency of search in minutes
  • score_based_kpis - list of KPIs which is added as part of a composite KPI. Each object in the list must have kpiid - <kpi id>, serviceid - <service id>, urgency - <urgency value>

Multi-KPI alert object schema:

  • time_label - time label for time range
  • percentage_based_kpis - list of KPIs and service IDs included. Each item should contain kpiid - <kpi id>, serviceid - <service id>, label_thresholds - <threshold and operation type for trigger>. label_thresholds data format is as follows:

{ operation : 'OR', // default for now thresholds : [ { severity: <severity name>, percentage: <percentage value>, percentage_operation: '>=', // default for now } ...... ] }

action.itsi_event_generator.param.editor String One of two values: advance_correlation_builder_editor or multi_kpi_alert_editor. It directs to the specific UI page to make edits based on the type of search, correlation search or multi-KPI alert.
action.itsi_event_generator Integer Value: 1
actions String Value: itsi_event_generator
alert.suppress Integer Enable suppression to minimize the number of duplicate notable events sent to Episode Review. Values: 1 (means enabled) or 0 (means disabled).
alert.suppress.fields String The fields to consider when determining if another event matches the current one.
alert.suppress.period String The number of seconds to ignore other events that have the same field values.
action.rss Integer Included in RSS feed. Values: 1 (means enabled) or 0 (means disabled).
action.email Integer Send an email when the alert is triggered. Values: 1 (means enabled) or 0 (means disabled).
action.email.to String The email addresses to send the email to.
action.email.subject String The subject of the email.
action.email.sendcsv Integer Send an email in CSV format. Values: 1 (means enabled) or 0 (means disabled).
action.email.sendpdf Integer Send an email with a PDF attachment. Values: 1 (means enabled) or 0 (means disabled).
action.email.inline Integer Send an email with the text inline. Values: 1 (means enabled) or 0 (means disabled).
action.email.format String Default value is pdf. Other values: html, csv.
action.email.sendresults String Include alert information as an email attachment. Values: 1 (means enabled) or 0 (means disabled).
action.script Integer Triggers a shell script if enabled. Values: 1 (means enabled) or 0 (means disabled).
action.script.filename String Provide the file name of the shell script to run when this alert is triggered.

Service Analyzer

Description

Service Analyzer is the ITSI UI home page. It displays service and KPI health scores that are trending at top severity levels. You can configure Service Analyzer to filter the display of services and KPIs relevant to the user.

The Service Analyzer object is called home_view.

Attributes

Field Type Description
_key String Unique ID for the entry in KV store.
object_type String home_view
-owner String User that creates the saved service analyzer.
title String User given title for the service analyzer.
earliest_time String Earliest time for the searches.
latest_time String Latest time for the searches.
serviceWhitelist String List of filtered services.
kpiWhitelist String List of filtered kpis.
isServiceFilterEnabled Boolean True if services are filtered, false by default.
isKpiFilterEnabled String True if kpis are filtered, false by default.
serviceTilesSettings Object SeverityTilesSettingModel with number of kpi tiles and filter.
view String Determines if service analyzer view is standard or full screen. Standard is default.
isDefault String True if it is the default (standard) service analyzer, false otherwise.
titleSize String medium|large], large by default.
searchType String maxseverity] [aggregate|maxseverity] aggregate shows the most recent service value and the max severity is service value unless there is an entity value with worst severity.

Team

Description

Teams are used to restrict service-level information in the following objects:

  • Glass tables
  • Service analyzers
  • Deep dives
  • Episode Review
  • Correlation searches
  • Multi-KPI alerts

The team object is called team.

Attributes

Field Type Description
identifying_name String The name of the team. Does not have to match title.
acl String Access control list for the team. Must include itoa_admin.
title String User provided name of the team. Does not have to match identifying_name.
description String User provided description of the team.
children List List of private teams created in ITSI. For private teams, this field will be an empty list.
parents List The parent of this team. Cannot be configured in current release.
_key String Unique ID for the entry in KV store.

Anomaly Detection Algorithm Settings

Attributes

Field Type Description
Sensitivity Number Determines sensitivity of algorithm to variance in data. Note that acceptable values for both trending and cohesive algorithm sensitivity are between 0 and the sensitivity_max parameter value, as specified in the respective [trending:limits]and [cohesive:limits] stanzas, in mad.conf in the SA-ITSI-MetricAD namespace.
Last modified on 01 April, 2020
PREVIOUS
ITSI REST API reference
 

This documentation applies to the following versions of Splunk® IT Service Intelligence: 4.3.0, 4.3.1, 4.4.0, 4.4.1, 4.4.2, 4.4.3, 4.4.4


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