Set up entity-index mappings

Entity-index mappings optimize how logs Related Content (RC) retrieves log data. Administrators can enhance the performance and accuracy of log queries by explicitly defining relationships between observability entities (e.g. service.name, host.name, deployment.environment, and k8s.namespace.name) and specific Splunk index and sourcetype combinations. Entity-index mappings work for Splunk Cloud Platform, Splunk Enterprise, and Splunk Observability Cloud indexes. Entity-index mapping works for all versions of Splunk Cloud Platform, including both the Classic and Victoria experiences.

Benefits

The key benefits of setting up entity-index mappings are the following:

  • Improved query performance: Related Content avoids broad index=* searches, directly targeting the relevant indexes and sourcetypes.

  • Reduced SVC consumption: Efficient searching minimizes the resources consumed by your Splunk environment.

  • Increased accuracy of results: By guiding Related Content to the correct data sources, you ensure that only the logs needed for context are displayed.

Region and version availability

Entity-index mapping is available for Unified Identity customers as well as Log Observer Connect customers. Entity-index mappings work for indexes in Splunk Cloud Platform, Splunk Enterprise, and Splunk Observability Cloud. Entity-index mapping works for all versions of Splunk Cloud Platform, including both the Classic and Victoria experiences.

Prerequisites: Configure log field aliases

Before generating entity-index mappings, admins must configure accurate log field aliases. These aliases instruct the system on how the field names in your Splunk logs correspond to standard observability entity names. Incorrect or missing aliases are the most common cause of mapping generation issues.

See the “Create a new field alias” section in Create field aliases to learn how to configure log field aliases. You must, at a minimum, alias the following entities:

  • service.name

  • deployment.environment

  • host.name

  • host.id

  • k8s.cluster.name

  • k8s.workload.name

  • k8s.workload.uid

  • k8s.node.name

  • k8s.namespace.name

  • k8s.pod.uid

  • k8s.pod.name

  • container.name

  • container.id

  • k8s.service.name

  • k8s.service.uid

  • trace_id

If your indexes use different field names for the same concept (e.g., hostname and _sourcehost both representing host.name), you can define multiple aliases that all point to the same observability entity.

Set up entity-index mappings

After correctly configuring log field aliases, you can generate and manage your entity-index mappings. See the following 5 sections to for step-by-step instructions on entity-index mapping setup, management, and application:

Access entity-index mapping

To access entity-index mappings, take these steps:

  1. Navigate to Settings > Log Observer connections.

  2. On the Connections list, locate the Indexes with Mappings column. This column displays a ratio (e.g., 2 / 30), indicating how many indexes within that connection currently have mappings generated (numerator) out of the total indexes visible (denominator).

  3. To open the mapping screen for a specific connection, select the link in the Indexes with Mappings column next to the desired connection. Alternatively, select the three-dot menu next to the desired connection, then select View Mappings or Generate Mappings.

Generate mappings

Within a connection's mapping area, you will find two primary tabs: Generation Mappings and Entity Mappings. Take these steps:

  1. Select the Generation Mappings tab. This tab lists all indexes available to the connection.

  2. Select one or more indexes for which you want to generate mappings.
    Note: To ensure reliable results, reduce load, speed validation, and simplify troubleshooting, generate mappings in small batches of no more than 10% of indexes per run. For example, if a connection has 100 indexes, start with no more than 10 indexes.

  3. Select Generate Mappings.

  4. Remain logged in. The system processes mapping generation requests asynchronously. You do not need to keep the mapping screen open. However, you must remain logged in for the results to persist and the Entity Mappings table to populate upon job completion.

  5. Monitor Status. The request progresses through a lifecycle is as follows: Accepted → In Progress → Completed or Failed. Select Reload to refresh the generation statuses.

  6. Select Regenerate if a job fails or if you need to refresh mappings for previously processed indexes. Regeneration appends newly discovered mappings and updates existing ones for the selected indexes, leaving other mappings unchanged.

Manage and review mappings

  1. Select the Entity Mappings tab. This tab displays the current mappings.

  2. Review the table. The table includes columns for Index, Sourcetype, Entity Type, Entity Value, Last Updated, and Last Updated By to support governance and auditability.

  3. Use the search capability to filter the table by Index, Entity Type, or Entity Value to quickly locate specific mappings.

  4. Adjust the page size (20, 50, or 100 rows of mappings per page) as needed.

  5. Note the mapping categories:

    • Auto Mappings are created automatically by the system based on your configured log field aliases. You can select multiple rows of auto-generated mappings and delete them in bulk if necessary.

    • Manual Mappings are created by administrators to address special cases or fill gaps that automation cannot resolve. To add a manual mapping, select Add Mappings, specify the entity type and value, and assign the relevant index and sourcetype. Manual mappings are useful if you want to add a mapping for any newly added service to the list instead of generating mappings again for that index.

    • Wildcard Mappings are for entities that change frequently (e.g., pods, containers, hosts), the system may create wildcard mappings (e.g., k8s.pod.name = *) to represent the correct index and sourcetype combinations without needing a mapping for every ephemeral value.

Control global index search

Each connection has an optional Global Index Search setting. Control this setting as follows:

  • Activate Global Index Search to set Related Content to an index=* search if it cannot find a specific mapping for an entity. While this can be a useful safety net during initial onboarding, it increases SVC consumption.

  • Deactivate Global Index Search after achieving sufficient mapping coverage to ensure that Related Content relies exclusively on your curated mappings, preventing unnecessary broad searches. Deactivating Global Index Search decreases SVC consumption and is therefore recommended.

Enable consumption in Related Content

After generating and reviewing your mappings, you must enable their consumption in Related Content.

To enable consumption in Related Content, follow these steps:

  1. Navigate to Settings > General settings.

  2. Ensure that Activate related content for logs is active.

  3. Select Activate related content mappings consumption for logs to apply your mappings. This setting instructs Related Content to use your defined mappings instead of performing broad index=* searches.

  4. Validate correct behavior. Open an entity view (e.g., a service or a Kubernetes object) and confirm that Related Content results are returned from the expected index and sourcetype combinations.

Best practices

To achieve the best outcomes with entity-index mappings, follow these guidelines:

  • Prioritize Log Field Aliases. Ensure your Log Field Aliases are complete and correct for all recommended entities. Gaps in aliasing are the most common cause of missing mappings.

  • Monitor Coverage. Use the "Indexes with Mappings (X / Y)" column on the Connections list to quickly gauge your mapping coverage and identify connections needing attention.

  • Generate in Small Batches. Always generate mappings in small batches (≤ 10% of indexes per run) to reduce load, speed validation, and simplify troubleshooting.

  • Disable Global Index Search. Once you have adequate mapping coverage, disable Global Index Search to optimize performance and reduce SVC consumption.

  • Use manual mappings sparingly to address specific exceptions or fill gaps while you work towards consistent field standards across your indexes.

Administrator checklist

Administrators can ensure full functionality of entity-index mapping by completing the following tasks:

  1. Configure Log Field Aliases for all recommended entities and verify their correctness.

  2. On your Splunk Observability Cloud connections list, preview the Indexes with Mappings column, open connections with gaps, and generate mappings for the required indexes in small batches.

  3. On the Entity Mappings tab, confirm expected mappings exist, add manual mappings if necessary, and use search and pagination for efficient validation.

  4. Disable Global Index Search once mapping coverage is satisfactory.

  5. In General Settings, select both Activate related content for logs and Activate related content mappings consumption for logs.

  6. Validate that Related Content queries resolve to the intended index and sourcetype combinations by checking entity views.