Splunk® IT Service Intelligence

Entity Integrations Manual

Acrobat logo Download manual as PDF


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

Create custom entity types in ITSI

You can create custom entity types in IT Service Intelligence (ITSI) to associate particular analysis data filters and navigations with custom entities. For more information about default entity types and analysis data filters, see Overview of entity types in ITSI.

Optionally, create analysis data filters, attach dashboards, and add navigations for each entity type. Analysis data filters, dashboards, and navigations are components of entity types and can't exist independent of entity types.

Entity types and their components are defined in $SPLUNK_HOME/etc/apps/SA-ITOA/default/itsi_entity_type.conf. For more information, see itsi_entity_type.conf in the Administration Manual. Entity type information is stored in the itsi_entity_type KV store collection.

Editing entity types through the UI or the REST API permanently unlinks them from the configuration file, so future changes to the file won't be reflected. Therefore, it's recommended that you avoid editing the configuration file and instead make all entity type modifications through the UI or the REST API to avoid confusion.

Here's an example entity type for a VMware cluster entity with events and metrics analysis data filters and a single default overview dashboard. Analysis data filters are called data_drilldowns and entity overview dashboards are called dashboard_drilldowns. Each analysis data filter has example static filters and entity filters.

Example VMware Cluster entity type

[vmware_cluster]
title = VMware Cluster
description = VMware Cluster type
data_drilldowns = [ \
    { \
        "title": "VMware Cluster metrics", \
        "type": "metrics", \
        "static_filter": { \
            "type": "include", \
            "field": "metric_name", \
            "values": ["vsphere.cluster.*"] \
        }, \
        "entity_field_filter": { \
            "type": "and", \
            "filters": [ \
                { \
                    "type": "entity", \
                    "data_field": "moid", \
                    "entity_field": "moid" \
                }, \
                { \
                    "type": "entity", \
                    "data_field": "vcenter", \
                    "entity_field": "vcenter" \
                } \
            ] \
        } \
    }, \
    { \
        "title": "VMware Inventory logs", \
        "type": "events", \
        "static_filter": { \
            "type": "include", \
            "field": "index", \
            "values": ["vmware-inv"] \
        }, \
        "entity_field_filter": { \
            "type": "entity", \
            "data_field": "moid", \
            "entity_field": "moid" \
        } \
    }, \
    { \
        "title": "VMware Cluster Events logs", \
        "type": "events", \
        "static_filter": { \
            "type": "and", \
            "filters": [ \
                { \
                    "type": "include", \
                    "field": "index", \
                    "values": [ \
                        "vmware-taskevent" \
                    ] \
                }, \
                { \
                    "type": "include", \
                    "field": "sourcetype", \
                    "values": [ \
                        "vmware_inframon:events" \
                    ] \
                }, \
                { \
                    "type": "include", \
                    "field": "computeResource.computeResource.type", \
                    "values": [ \
                        "ClusterComputeResource" \
                    ] \
                } \
            ] \
        }, \
        "entity_field_filter":{ \
            "type": "entity", \
            "data_field": "computeResource.computeResource.moid", \
            "entity_field": "moid" \
        } \
    } \
]
dashboard_drilldowns = [ \
    { \
        "title": "VMware Cluster Overview Dashboard", \
        "id": "vmware_cluster_overview_dashboard", \
        "base_url": "", \
        "is_splunk_dashboard": false, \
        "params": { \
            "static_params": {}, \
            "alias_param_map": [] \
        } \
    } \
]
vital_metrics = [ \
    { \
        "metric_name": "Average CPU Usage", \
        "search": "| mstats avg(vsphere.cluster.cpu.usage) as val WHERE `itsi_entity_type_vmware_cluster_metrics_indexes` by moid,vcenter span=5m", \
        "split_by_fields": ["moid", "vcenter"], \
        "matching_entity_fields": ["moid", "vcenter"], \
        "is_key": 1, \
        "unit": "%" \
    }, \
    { \
        "metric_name": "Average Effective Memory", \
        "search": "| mstats avg(vsphere.cluster.clusterServices.effectivemem) as val WHERE `itsi_entity_type_vmware_cluster_metrics_indexes` by moid,vcenter span=5m", \
        "split_by_fields": ["moid", "vcenter"], \
        "matching_entity_fields": ["moid", "vcenter"], \
        "is_key": 0, \
        "unit": "MB" \
    }, \
    { \
        "metric_name": "Hosts Up", \
        "search": "search index=vmware-inv sourcetype=vmware_inframon:inv:hostsystem | spath moid output=moid | spath changeSet.summary.runtime.powerState output=powerState | search powerState=poweredOn | bin span=1h _time | stats distinct_count(moid) as val by cluster.moid host _time | rename \"cluster.moid\" as moid", \
        "split_by_fields": ["moid", "host"], \
        "matching_entity_fields": ["moid", "vcenter"], \
        "is_key": 0, \
        "unit": "" \
    }, \
    { \
        "metric_name": "Triggered Alarms", \
        "search": "search index=vmware-taskevent sourcetype=vmware_inframon:events | spath entity.entity.moid output=moid | spath entity.entity.type output=etype | search moid=* etype=ClusterComputeResource | search eventClass=AlarmActionTriggeredEvent | eval isAlarmTriggered=if(eventClass=\"AlarmActionTriggeredEvent\",1,0) | bin span=1h _time | stats sum(isAlarmTriggered) by host, moid _time", \
        "split_by_fields": ["moid", "host"], \
        "matching_entity_fields": ["moid", "vcenter"], \
        "is_key": 0, \
        "unit": "" \
    } \
]

Create an entity type

Create entity types to associate different kinds of entities with each other. You can use this association to visualize and troubleshoot entities of that specific type. For example, you can group entities by entity type in the Infrastructure Overview to visualize key metrics relating to the health of that entity type. View and manage entity types from the entity type lister page.

Use the entity type name to associate entities with it. When you import entities from a Splunk search or CSV, include a column entry that exactly matches the name of an existing entity type, otherwise the import process ignores the entity type field. For more information, see Associate entities with an entity type in ITSI.

Associate navigations and analysis data filters with an entity type to power entity visualizations. These components populate dashboards for entities you associate with an entity type. For more information about how these components help you visualize entity data, see Overview of entity types in ITSI.

Prerequisites

Requirement Description
ITSI roles You need to log in as a user with the itoa_admin or itoa_team_admin role.

Steps

When you create an entity type, you can also add navigations and analysis data filters for it. If you don't add navigations or analysis data filters now, you can add them later.

Step 1: Create an entity type

  1. From the ITSI main menu, go to Configuration > Entities.
  2. Select the Entity types tab.
  3. Click Create Entity Type.
  4. Specify entity type information. Enter an Entity type name to reference the entity type.
  5. Optionally, provide a description of the entity type for yourself or other users.

Step 2: Add navigations to your entity type

Navigations are external URLs that pass entity parameters belonging to the entity type to the URL. For example, if you enter http://buttercup.com as the URL and make the entity parameter host=hostname, the resulting link will be http://www.butter.com?hostname=splunk.com, if the entity has a host value equal to "splunk.com".

If you enter a single word as the URL, like user_dashboard, ITSI assumes you entered a custom dashboard in Splunk. The resulting link would be <user_splunk_host>:<port>/en-US/app/itsi/user_dasboard.

Configure the following fields:

Field Description
Navigation name A name to reference the navigation later. You see this name as a link on the side panel of the entity health page. It should be a unique name.
URL The resource you want to associate with entities that belong to the entity type. It can be a Splunk Web URL or a completely external URL.

You can also substitute entity fields directly in the URL. For example, https://www.${host}.com. In this example, when the URL is constructed for an entity associated with that entity type, it uses the host field of that specific entity instead of a static URL. You can also use multiple fields for substitution. For example, http://${url}.${host}.${title}.${entity_title}.${remote_host}.

Entity parameters Optionally, specify parameters to pass information about entities in the URL when you go to the navigation. Select entity informational fields or alias fields from the dropdown menu. The field has to already exist in ITSI. If you want to add entity fields for the navigation that don't already exist in ITSI, you can save the configuration and come back later to add them once entities contain those fields.

Click Save navigation when you're done.

Step 3: Add Splunk dashboards to your entity type

You can attach one or more Splunk XML dashboards to your entity type. The dashboards appear on the entity health page of every entity associated with the entity type. The dropdown only lists the dashboards you have permission to view.

  1. Click Select a dashboard and select a dashboard in your Splunk environment.
  2. Click Add.

Step 4: Add analysis data filters to your entity type

Analysis data filters determine which data sources you associate with the entity for visualizations in an entity's Analytics dashboard You can create filters to define data sources for metrics and logs here.

Field Description
Analysis data filter Enter a name to reference the filter later. You can see metrics and events associated with each filter from the Analytics dashboard. You can add multiple static filters and entity filters to define as broad or specific an analysis data filter as needed. You can also include multiple analysis data filters for each entity type.
Type Whether the filter is for metrics or events. Each filter can define data sources for only metrics or only events, not both. Add multiple filters to define data sources for metrics and events.
Static filter Add field-value pairs to define a data source. This filter isn't entity-specific. It can be as broad or specific as you want it to be. For example, use region = us-west-1 to include data from every entity with a region field in us-west-1, use metric_name = windows.* to include entity data for all Windows metrics. To take it a step further, you could use metric_name = windows.CPUUtilization.average to view data about only average Windows CPU utilization. For event-based analysis filters, the fields you filter by must be indexed fields.
Entity filter Field-value pairs to define entities associated with data that's defined in the static filter. This filter is entity-specific. For example, you can use host = buttercupgames.splunk.com or ip = 127.0.0.1. For event-based analysis filters, the fields you filter by must be indexed fields.

Click Save to save the analysis data filter and apply it to the entity type.

Add vital metrics to an entity type

The REST API itoa_interface/entity_type endpoint lets you create and modify vital metrics for an entity type, which you can't currently accomplish through the UI. Vital metrics are statistical calculations based on SPL searches that represent the overall health of entities of that type. For more information about vital metrics, see Investigate vital metrics for an entity type in the ITSI User Manual.

For the full vital metric schema reference, see Entity Type Vital Metrics in the REST API Reference manual.

Create an entity type with vital metrics

The following example request creates a new entity type with two vital metrics for CPU and memory:

Example request

curl -k -u admin:password 'https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity_type' --header 'Content-Type: application/json' -X POST -d '{"title": "My custom entity type","description":"This is my custom entity type","data_drilldowns": [],"dashboard_drilldowns": [],"vital_metrics": [{"metric_name": "Average CPU Usage","search": "| mstats avg(cpu.idle) as val WHERE index=my_custom_index by host span=10s | eval val=100-val","split_by_fields": ["host"],"matching_entity_fields": ["host"],"is_key": 1,"unit": "%"},{"metric_name": "Average Free Memory","search": "| mstats avg(memory.free) as val WHERE index=my_custom_index by host span=10s","split_by_fields": ["host"],"matching_entity_fields": ["host"],"is_key": 0,"unit": "%"}]}'

Expand to see formatted payload

{
    "title": "My custom entity type",
    "description": "This is my custom entity type",
    "data_drilldowns": [...],
    "dashboard_drilldowns": [...],
    "vital_metrics": [
        {
            "metric_name": "Average CPU Usage",
            "search": "| mstats avg(cpu.idle) as val WHERE index=my_custom_index by host span=10s | eval val=100-val",
            "split_by_fields": [
                "host"
            ],
            "matching_entity_fields": [
                "host"
            ],
            "is_key": 1,
            "unit": "%"
        },
        {
            "metric_name": "Average Free Memory",
            "search": "| mstats avg(memory.free) as val WHERE index=my_custom_index  by host span=10s",
            "split_by_fields": [
                "host"
            ],
            "matching_entity_fields": [
                "host"
            ],
            "is_key": 0,
            "unit": "%"
        }
    ]
}


Add vital metrics to an existing entity type

The following example updates an existing entity type with vital metrics for CPU and memory:

Request

curl -k -u admin:password 'https://localhost:8089/servicesNS/nobody/SA-ITOA/itoa_interface/entity_type/5f7777ffaf3e3704a63d37c9?is_partial_data=1' --header 'Content-Type: application/json' -X POST -d '{"vital_metrics": [{"metric_name": "Average CPU Usage","search": "| mstats avg(cpu.idle) as val WHERE index=my_custom_index  by host span=10s | eval val=100-val","split_by_fields": ["host"],"matching_entity_fields": ["host"],"is_key": 1,"unit": "%"},{"metric_name": "Average Free Memory","search": "| mstats avg(memory.free) as val WHERE index=my_custom_index  by host span=10s","split_by_fields": ["host"],"matching_entity_fields": ["host"],"is_key": 0,"unit": "%"}]}'

Expand to see formatted payload

{
    "vital_metrics": [
        {
            "metric_name": "Average CPU Usage",
            "search": "| mstats avg(cpu.idle) as val WHERE index=my_custom_index  by host span=10s | eval val=100-val",
            "split_by_fields": [
                "host"
            ],
            "matching_entity_fields": [
                "host"
            ],
            "is_key": 1,
            "unit": "%"
        },
        {
            "metric_name": "Average Free Memory",
            "search": "| mstats avg(memory.free) as val WHERE index=my_custom_index  by host span=10s",
            "split_by_fields": [
                "host"
            ],
            "matching_entity_fields": [
                "host"
            ],
            "is_key": 0,
            "unit": "%"
        }
    ]
}
Last modified on 11 December, 2020
PREVIOUS
Edit a default entity type in ITSI
  NEXT
Associate entities with an entity type in ITSI

This documentation applies to the following versions of Splunk® IT Service Intelligence: 4.7.0, 4.7.1, 4.7.2


Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters