ITSI REST API schema - Splunk Documentation (2024)

The IT Service Intelligence (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 here:

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
entity_type
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
notable_event_email_template
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 the object type.
create_by	String	The user who created this object.
create_source	String	The sourcetype initiating create. Has value `manual` for user-initiated creates. For internal use only.
create_time	String	Timestamp at the time of creation based on UTC time zone.
mod_source	String	Sourcetype initiating modification. Has value `manual` for user-initiated modifications. For internal use only.
mod_time	String	Timestamp of the last modification based on UTC time zone.
_owner	String	Splunk user `nobody`.
_user	String	User who performed the most recent operation on this object.
version	String	The version of the object. Currently the same as the ITSI app version.

Common attributes are omitted from the object schemas in this topic 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. Can be any unique value.
title	String	Name of the entity. Can be any unique value.
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.
entity_type_ids	Array	Array of _key values for each entity type associated with the entity.

For more information, see Overview of entity integrations in ITSI in the Entity Integrations 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.
service_tags	Object	The tags for the service. The `service_tags` object can have an array for `tags` and `template_tags`. `tags` are regular tags that are added manually and `template_tags` are tags that are populated from a service template. Tags have to be strings and can't contain the following characters: `/ \ " '! @? . ,; $ ^` Example `service_tags` object: "service_tags": { "tags": [ "unix", "seattle" ], "template_tags": [ "cloud_systems", "us-west" ] },

For more information, see Overview of creating services in ITSI in the Service Insights manual.

Subordinate objects

Entity Rules
Service KPI

Service Template

Description

ITSI service templates help you 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.

The base_service_template object contains KPI definitions, entity rules, and any linked services.

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	Integer	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	String	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".
template_tags	Array	The service tags contained within the template.

Subordinate objects

Entity Rules
Service Template KPI

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 separated by OR at the top level.

Field	Type	Description
rule_condition	Boolean operator	Uses the value AND indicating this rule appends all nested rules contained in the `rule_items` attribute.
rule_items	Array	Array of rules that are appended 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 whether it's 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 examples

The following examples 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" } ] }]

Entity Type

Description

An entity_type defines how to classify a type of data source. For example, you can create a Linux, Windows, Unix/Linux add-on, VMware, or Kubernetes entity type. An entity type can include zero or more data drilldowns and zero or more dashboard drilldowns. You can use a single data drilldown or dashboard drilldown for multiple entity types.

Attributes

Field	Type	Description
title	String	The name of the entity type.
description	String	A description of the entity type.
dashboard_drilldowns	Array	An array of dashboard drilldown objects. Each dashboard drilldown defines an internal or external resource you specify with a URL and parameters that map to one of an entity fields. The parameters are passed to the resource when you open the URL. See Entity Type Dashboard Drilldown.
data_drilldown	Array	An array of data drilldown objects. Each data drilldown defines filters for raw data associated with entities that belong to the entity type. See Entity Type Data Drilldown.
vital_metrics	Array	An array of vital metric objects. Vital metrics are statistical calculations based on SPL searches that represent the overall health of entities of that type. See Entity Type Vital Metrics.

Subordinate objects

Entity Type Dashboard Drilldown
Entity Type Data Drilldown
Entity Type Vital Metrics

Entity Type Dashboard Drilldown

Description

A dashboard_drilldown lists the dashboards associated with an entity and its entity type.

Attributes

Field	Type	Description
title	String	The name of the dashboard.
id	String	A unique identifier for the dashboard.
base_url	String	An internal or external URL that points to the dashboard. This setting exists because for internal purposes, navigation suggestions are treated as dashboards. This setting is only required if `is_splunk_dashboard` is `false`.
is_splunk_dashboard	Boolean	`true` if the dashboard is a Splunk XML dashboard. If it's another dashboard type such as a JSON dashboard from the Splunk Dashboards app, or if it's a navigation link, this value is `false`.
dashboard_type	String	The type of dashboard being added. This element is required. The following options are available: `xml_dashboard` - a Splunk XML dashboard. Any dashboards you add must be of this type. `navigation_link` - a navigation URL. Should be used when `base_url` is specified.
params	Object	A set of parameters for the entity dashboard drilldown that provide a mapping of a URL parameter and its alias and static parameters.

Entity Type Data Drilldown

Description

A data_drilldown is a basic unit of configuration for an entity type. Entity data drilldown specifies filters that correlate raw data in Splunk indexes with an entity.

Attributes

Field	Type	Description
title	String	Name of the drilldown.
type	String	Type of raw data to associate with. Must be either `metrics` or `events`.
static_filter	Object	Filter down to a subset of raw data associated with the entity using static information like sourcetype.
entity_field_filter	Array	Further filter down to the raw data associated with the entity based on a set of selected entity alias or informational fields.

Entity Type Vital Metrics

Description

vital_metrics are a basic unit of configuration for an entity type. Vital metrics are statistical calculations based on SPL searches that represent the overall health of entities of that type.

Attributes

Field	Type	Description
metric_name	String	The title of the vital metric. When creating vital metrics, it's a best practice to include the aggregation method and the name of the metric being calculated. For example, `Average CPU usage`.
search	String	The search that computes the vital metric. The search must specify the following fields: `val` for the value of the metric. `_time` because the UI attempts to render changes over time. You can achieve this by adding `span={time}` to your search. Fields as described in the `split_by_fields` configuration of this vital metric. For example, your search should be split by `host,region` if the `split_by_fields` configuration is [ "host", "region" ].
split_by_fields	Array	The fields that the `search` configuration is split on. Make sure the value matches the split by fields in the actual search. For example: search = "..... by host, region" split_by_fields = ["host", "region"]
matching_entity_fields	Array	Specifies the aliases of an entity to use to match with the fields specified by `split_by_fields` in the search result. The order of values should match the order of split_by_fields and the mapping is 1 to 1, so they must be of the same length. For example: split_by_fields = ["InstanceId", "region"] matching_entity_fields = ["instance_id, zone"] You can only use entity aliases for this field, not informational fields
is_key	Boolean	Indicates if the vital metric specified is a key metric. A key metric calculates the distribution of entities associated with the entity type to indicate the overall health of the entity type. The key metric is rendered as a histogram in the Infrastructure Overview. Only one vital metric can have `is_key` set to `true`.
unit	String	The unit of the vital metric. For example, `KB/s`.
alert_rule	Object	Displays vital metric alert threshold information. The following parameters are displayed: `suppress_time`: suppress the alert until this time `cron_schedule`: frequency of alert search `is_enabled`: if alert is enabled `critical_threshold`: range of values that indicate critical severity level `warning_threshold`: range of values that indicate warning severity level `info_threshold`: range of values that indicate info severity level `entity_filter`: filter entities based on the field dimensions For example: entity_filter: [{"field":"os", "value":"Ubuntu", "field_type":"info"}]

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.

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_threshold_template_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	Array	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	Integer	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	Integer	Contains the number of seconds of lag to apply to the alert search. The maximum value 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	Objects	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.
aggregate_outlier_detection_enabled	Boolean	Indicates if outlier exclusion is turned on for KPI.
outlier_detection_algo	String	Determines the outlier detection algorithm.
outlier_detection_sensitivity	String	The trigger threshold of the algorithm. For the standard deviation, this is the number of standard deviations. For interquartile range and mean absolute deviation, this is the sensitivity value.

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. You can't enable anomaly detection 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_threshold_template_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	Array	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	Integer	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	Integer	Contains the number of seconds of lag to apply to the alert search. The maximum 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_specification_custom	Boolean	If true, thresholds for alerts are pulled from time_variate_thresholds_specification.
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
Time Variate Thresholds Specification
Anomaly Detection Algorithm Settings

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	Integer	Minimum value for the threshold gauge specified by user.
gaugeMax	Integer	Maximum value for the threshold gauge specified by user.
search	String	Generated search used to compute the thresholds for this KPI.
baseSeverityValue	Integer	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	Integer	Lower bound value to use to render the graph for the thresholds.
renderBoundaryMax	Integer	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

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	Integer	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	Integer	Severity value assigned for this threshold level.
severityLabel	String	Severity label assigned for this threshold level like info, warning, critical, etc.
dynamicParam	Integer	Value of the dynamic parameter for adaptive thresholds.

KPI Threshold Templates

Description

A kpi_threshold_template is a set of predefined 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 adaptive threshold training algorithm to run over. The 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 KPI base searches in ITSI in the Service Insights 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
Glass Table Icon

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	Integer	Numeric indication of which visualization 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	Integer	Initial width to use for the widget.
defaultHeight	Integer	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	Integer	Width of the icon.
default_height	Integer	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

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: <Data Model name> 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 (Monday) through 6 (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 doesn't 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 Administration 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 put services and entities in maintenance mode at required intervals.

Attributes

Field	Type	Description
_key	String	Unique ID for the entry in the KV store.
title	String	Title of the maintenance window.
comment	String	Optional description of the maintenance window.
objects	Array	Array of dictionaries describing the objects put in maintenance by this maintenance window. The 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 supported.
start_time	String	Timestamp that marks the beginning of maintenance window. Based on UTC time.
end_time	String	Timestamp that marks the end of maintenance window. Based on UTC time.

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

Event Management Export

Description

itsi_event_management_export contains information about an episode.

Attributes

Field	Type	Description
export_filename	String	The file name for the new file export.
object_type	String	event_management_export
status	String	The status of the CSV file export: started, in progress, failed, completed.
_owner	String	The Splunk user who owns the CSV file.
_key	String	A unique identifier to determine the CSV file object.