
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 - Info2 - Normal3 - Low4 - Medium5 - High6 - 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 - Unassigned1 - New2 - In Progress3 - Pending4 - Resolved5 - 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:
Multi-KPI alert object schema:
|
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.
|
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, 4.4.5
Feedback submitted, thanks!