Splunk® IT Service Intelligence

Administer Splunk IT Service Intelligence

Download manual as PDF

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

Define entities in ITSI

In ITSI, an entity is an IT component that requires management to deliver an IT service. Each entity has specific attributes and relationships to other IT processes that uniquely identify it. Entities are usually hosts, but can also be items as diverse as network devices, applications, users, and cell towers.

ITSI entities can be any of the following components:

  • Physical or virtual hosts
  • Network devices (switches, routers)
  • Users (AD/LDAP)
  • Storage systems, volumes
  • Operating system processes
  • Software application (db, web server, business app)
  • Application process instances (for example, 2 instances of the same web server application is 2 separate entities)
  • Cell towers

Entities contain information that ITSI uses to associate services with information found in Splunk searches. You can use this entity information to filter items according to the entity definition.

An entity is similar to a "configuration item" in the ITIL framework, but an entity is never a service itself.

Define entities before creating services. When you configure a service, you can specify entity matching rules based on entity aliases that automatically add the entities to your service. For more information, see Configure services in ITSI in this manual.

How to define entities

There are four ways to create entities in ITSI:

All entities exist in the Global team. Only a user with write permissions to the Global team can create a single entity. Only a user with the itoa_admin role can import entities from CSV files or searches.

Auto-detect entities using ITSI modules

The modules included with ITSI can help automatically discover entities. For example, when a new server comes online, ITSI can automatically add it as an entity. Entity discovery occurs on a scheduled basis (usually every 4 hours) if the modules included with ITSI are properly configured and the add-ons required for data collection are installed and properly configured.

For example, the OS module automatically detects all the servers that are sending data into the Splunk platform using the Splunk Add-on for Unix and Linux or the Splunk Add-on for Microsoft Windows. Entity types such as OS hosts, virtualization hypervisors, VMs, web servers, database servers, and load balancers can all be created and populated as entities in ITSI in this way. For more information, see ITSI module entity discovery in the Splunk IT Service Intelligence Modules manual.

Create a single entity

You can create single entities one at a time in the UI.

  1. Click Configure > Entities.
  2. Select Create Entity > Create Single Entity. The Create Entity dialog opens.

    If your role does not have write access to the Global team, you will not see the Create Entity option.

  3. Configure the following fields to define your new entity:
    Field Description
    Name The name of your new entity.
    Description (Optional) Enter a brief description of the entity.
    Team All entities are created in the Global team. This cannot be changed.
    Aliases Enter field-value pairs that identify the entity. For example:
    host=webserver-01
    IP=10.2.1.1
    MAC=C6:4B:B9:E8:E6:2A.
    Info Fields Add field-value pairs that associate specific attributes with the entity. For example:
    role=webserver
    owner=Ops

    The following characters are not supported in fields for field-value pairs: commas (,) single quotes ('), double quotes ("), $ (as first character in field name), period (.), equal sign (=), and spaces( ).

  4. Click Create. Your new entity appears in the Entities lister page.
  5. (Optional) Click View Health to view detailed entity information, including the health status of associated services and KPIs.

Bulk import entities

ITSI provides two methods for bulk import of entity definitions:

Import from CSV
Import entity definitions from a CSV file.
Import from search
Import entity definitions from ITSI module searches, saved searches, and ad hoc searches.

By default, only a user with the itoa_admin role can perform bulk imports of entities.

Use cases

Create entities in ITSI
Create a CSV file or a search with the results in table format with a column to use for the entity title and optionally, one or more entity alias and entity information columns. The columns do not need to use these exact names as they will be mapped in the import process.
Create entities in ITSI and associate each entity with a service
Add a Service column containing the name of the service in addition to a column for the entity title and optionally, one or more entity alias and entity information columns. If the service does not already exist, the service will be created. To associate multiple entities to a service, provide multiple rows that contain the same service and the name of each unique entity. An entity rule will be created for the service with Entity Title matches <value from Entity Title column> for each entity.

For information about creating services and linking them to service templates, see Bulk import services in ITSI.

Import from CSV

You can import entities from CSV files that contain one or more entity definitions. Importing entities from CSV files is an efficient way to define multiple entities. You can dump data from a change management database (CMDB) or asset inventory database into a CSV file. The CSV import can be automated for ongoing updates.

In the first row of the CSV, specify column names. In each subsequent row, specify an entity title, as well as one or more entity aliases, and one or more entity information fields. To associate an entity with a service, provide a column with the name of the service.

Import from CSV has a limit of one service and one entity per row. There is no limit on the number of dependent services, entity aliases, or entity rule values per row. A CSV file can contain multiple rows. Import from CSV supports five different separators: comma (,), semicolon (;), pipe (|), tab (\t), and caret (^).

Prerequisite

To import entities from CSV, you must create a CSV file that contains your entity definitions. In this example we want to create two entities called appserver-04 and appserver-05, and associate appserver-04 with the Web A service and associate appserver-05 with the Web B service. The Web A service already exists in ITSI but the Web B service does not.

Entitiescsv.png

Steps

  1. Click Configure > Entities.
  2. Click New Entity > Import from CSV.

    If your role does not have write access to Global team, you will not see the New Entity button.

  3. Click browse... and select your CSV file, or drop it into the UI.
    The CSV file uploads and a file preview appears.
    EntitiesPreview.png
  4. Click Next.
  5. Under Import Column As, select the appropriate column type for each column.
    Column type Description
    Entity Title Makes the column entry the entity title.
    Entity Description Makes the column entry a description of the entity.
    Entity Alias Makes the column entry a searchable entity identifier.
    Entity Information field Makes the column entry a tag that provides user-facing validation.
    Service Title Makes the column entry the name of the service to associate the entity with. The service will be created if it does not already exist.
    Service Description Makes the column entry the description of the service.
    Do Not Import Removes the column entry from the imported data.

    You can edit the Column Name field for columns that you import as Entity Title, Entity Alias, and Entity Information, for custom field mappings.

    For this example, we map the columns in the CSV file to the following fields in ITSI:
    ColumnEntities .png

  6. In the Settings section, choose a Conflict Resolution option to determine how ITSI will update and store your entity data:
    • Skip Over Existing Entities: Adds all new entity data to the datastore.
    • Update Existing Entities: Combines two records into a single record.
    • Replace Existing Entities: Replaces existing entity data with new entity data.
    For more information about Conflict Resolution, see Conflict Resolution examples below.
  7. If you are also importing services, configure the following options in the Settings section:
    Option Description
    Service Team Select the team to create the services in. (Entities can only be created in the Global team.)
    Import Services As Choose whether services are enabled or disabled upon import.
  8. Click Import.
  9. Click View all Entities and View all Services to confirm that your imported entities and services appear.
    For example, for service Web A (which already existed), an Entity Title matching rule has been added for appserver-04. appserver-04 is listed in the table of matching entities and the aliases and Information fields have been added to the entity from the CSV file.
    WebAEntities.png
    We also see that the service Web B has been created and that an Entity Title matching rule has been added for appserver-05. We see appserver-05 listed in the table of matching entities at the bottom and we see the aliases and information fields have been added to the entity from the CSV file.
    WebBEntities.png
  10. (Optional) Click Set up Recurring Import to create a modular input for the CSV file. For more information, see Set up recurring import in this manual.

Import from search

ITSI lets you import multiple entities from ITSI module searches, saved searches, or ad hoc searches using any data coming into the Splunk platform. The Import from Search workflow is identical to the Import from CSV workflow, except that you specify a search string instead of uploading a CSV file.

For CMDB integration, you can set up the Splunk platform to directly query the database where the CMDB data is stored so that a Splunk search can be used to import the CMDB data into ITSI as entities. The import from search can be automated for ongoing updates.

  1. Click Create Entity > Import from Search.

    If your role does not have write access to the Global team, you will not see the Create Entity option.

  2. Select one of the following search types:
    Search Type Description
    Module Choose from a list of pre-defined entity discovery searches based on ITSI modules.
    Saved Searches Choose from a list of pre-defined ITSI saved searches.
    Ad hoc Search Enter a custom search string.
  3. Enter an ad hoc search string or select a pre-defined module search or saved search. Make sure the results are presented in a table.
    In this example we want to import entities using an ad hoc search.
  4. Click the Search icon to view a preview of the search results. ImportEntity.png
  5. Click Next.
  6. Use the Select Column page to specify how to classify and store the file column entries that define your entities.
    In this example, we select to import the title column as Entity Title and the hostname column as Entity Alias. SpecifyColumns.png
  7. In the Settings section, select a conflict resolution option to determine how ITSI will update and store your entity data:
    • Skip Over Existing Entities: Adds all new entity data to the datastore.
    • Update Existing Entities: Combines two records into a single record.
    • Replace Existing Entities: Replaces existing entity data with new entity data.
    For more information on Conflict Resolution see Conflict Resolution examples below.
  8. In the Preview section, click Entities to be imported to confirm that your entity import configuration is correct.
    PreviewEntityImport.png
  9. Click Import.
    A message appears confirming that the import is complete.
  10. Click the View all Entities link to confirm your imported entities appear in the Entity viewer page.
  11. Click Set up Recurring Import to create a modular input for the CSV file. See Set up recurring import below.

For an example of importing both entities and services, see the Import from CSV section.

Set up recurring import

After the bulk import process is complete, ITSI gives you the option of creating a modular input that repeats the import function on a recurring basis. This is convenient if you want to add or update entities or services without repeating the entire import from CSV or search workflow.

In a search head cluster environment, you cannot enable the modular input for the recurring import from the UI as described in the steps below. Configure modular inputs on individual search head cluster members. To do so, copy the inputs.conf file that you've created on a search head into shcluster/apps manually and let the deployer push it to cluster peers. Note that when you redeploy the configuration via the deployer, the configuration is overwritten. If you place the CSV modular input on a single search head using the deployer, the modular input works, but logs will show error messages on the machines where the modular input does not exist.

  1. After the import from CSV or search process is complete, click Set up Recurring Import.
  2. Provide a name for the recurring input.
  3. In the case of Import from CSV, enter the full path to the CSV file on the server.

    The CSV file must be on the same server as your ITSI installation.

  4. Set the scheduled time to run the import.
  5. Click Submit.
    ITSI creates a new modular input of type "IT Service Intelligence CSV Import".

For more information, see Modular inputs overview in the Developing views and apps for Splunk Web manual.

If you configure a search-based modular input via the deployer, and you use the append mode, duplicate entities will be created.

Conflict resolution examples

When you import entities from CSV or search, you must select a conflict resolution type. This determines how ITSI updates and stores your entity data. The following examples demonstrate the behavior of each conflict resolution type.

Skip Over Existing Entities: Adds all new entity data to the datastore. For example, if we import the following CSV file, all of the entity data in the file is added to the datastore:

title, IP, host
Server_1, 192.168.1.1, somehostName
Server_2, 192.168.2.2, anotherhostName

Update Existing Entities: Combines the two records into a single record, merging the attributes (aliases and identifiers) of both. For example, if we now import this entity definition:

title, IP, host
Server_1, 192.168.1.1, somehostName
Server_2, 192.168.2.22, anotherhostName

Server_2 will now have 2 IPs (192.168.2.2 and 192.168.2.22), while no new data is added to Server_1.

Replace Existing Entities: Replaces existing entity data with new entity data. For example, if we now import this updated entity definition:

title, IP, host
Server_1, 192.168.1.11, somehostName
Server_2, 192.168.2.2, anotherhostName

The Server_1 IP (192.168.1.11) in our new entity definition replaces the Server_1 IP (192.168.1.1) in our existing entity definition, and the existing Server_1 IP is removed.

About duplicate entity aliases

Entity aliases must uniquely identify the entity. For example, host=appserver-01. The same alias field value cannot be used for more than one entity. If more than one entity is using the same alias field value (such as appserver-01), this can cause incorrect statistical aggregation results for KPI base searches.

For information on how to find and fix duplicate entity aliases, see Duplicate entity aliases in the Troubleshooting section.

PREVIOUS
Overview of creating services in ITSI
  NEXT
Create a single service in ITSI

This documentation applies to the following versions of Splunk® IT Service Intelligence: 4.0.0, 4.0.1, 4.0.2, 4.0.3, 4.0.4


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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

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

0 out of 1000 Characters