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.

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

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 group entities of the same kind together. You can use this grouping 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 vital metrics to your entity type

Vital metrics are statistical calculations based on SPL searches that represent the overall health of entities of that type. Vital metrics can search against both metrics and logs data, while the search result must include a metric field whose values are timestamped. Examples of vital metrics include average CPU usage, memory usage, disk availability, and network usage.

You can select an entity type within the Infrastructure Overview to further drill down to its entity health page, which displays the vital metrics for that entity type and the health of all entities of that type. You must designate one metric as the key metric, meaning it's the main statistic displayed in the Infrastructure Overview histogram. For more information about the Infrastructure Overview, see About the Infrastructure Overview in ITSI.

Perform the following steps to configure vital metrics for an entity type:

1. Click Add Metric and provide a name for your vital metric.
2. Provide the SPL search that calculates the value of the metric. The search must contain the following fields:

   Field	Description
   val	Specifies the value of the metric. For example, avg(LogicalDisk.%_Free_Space) as val.
   _time	The UI attempts to render changes over time. You can achieve this rendering by adding span={time} to your search. For example, bin span=1h _time.

3. (Optional) Click Add a matching field to add entity matching fields, which are the fields used to look up entities from the KV store. Add a field to split from your search results and select an entity alias field to match it with. For example, you could include the following matches:
   
   • InstanceId = instance_id
   • region = zone
     
   InstanceId and region are used to split the metrics by entities associated with the entity type, which enables ITSI to calculate the distribution of values to display in the histogram. instance_id and zone are the aliases used to match with the fields specified by the split fields.
4. Choose a key metric, which is the main statistic displayed in the Infrastructure Overview histogram.
5. When you're finished adding all your vital metrics, click Save in the modal.

Step 3: 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 4: 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. Custom dashboard aren't supported within entity types.

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

Step 5: 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 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.

Create an entity type through the REST API

The REST API itoa_interface/entity_type endpoint lets you create and modify entity types.

For the full schema reference for the entity_type object and all subordinate objects, including data drilldowns, dashboard drilldowns, and vital metrics, see Entity Type in the REST API Reference manual.

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": "%"
        }
    ]
}