Optimizing your Insights configuration

Introduction

By the end of this section you should be able to set up Insights in a way that optimizes the data you collect to ensure it's both accurate and helpful as you drive adoption of Backstage across your organization.

Overview

The Insights plugin is designed to help you enhance the usability and increase the usage of your Backstage instance, ensuring it aligns with the specific needs of your organization. To fully leverage its full set of capabilities, it's crucial that the plugin has access to all relevant data, including custom plugins, specific groups, and comprehensive data collection. Proper configuration of Insights is essential for achieving optimal performance and accurate data display.

In the context of using Insights, the are a few factors that can create "noise" or inaccuracies in the data presented to our adopters. Here are some key points to consider:

• Host Configuration

  • Issue: If you are capturing data across multiple environments (i.e. debug: false) and HostFilter is not configured correctly, Insights will display data from all environments, including localhost. This can result in a skewed representation of actual usage.
  • Impact: For larger organizations, this might be a minor issue, as non-production environment events are typically insignificant in volume. However, for smaller organizations, this can lead to misleading data due to their smaller user base.

• Total User Count

  • Issue: The total user count in Insights is a static figure based on the total user count within your catalog. If all users are ingested initially but only a subset (e.g., 10%) are actively participating in a pilot program, this can distort the perceived adoption rate.
  • Impact: For example, if only 10% of your organization's employees are "eligible" to use Backstage during a pilot phase, but the total user count includes all employees, it will appear that adoption is lower than you expect even if the pilot is progressing well. This discrepancy can hinder the ability to accurately assess progress.

Recommendations for Optimizing Insights

To ensure your Insights configuration is optimized, follow these recommendations. These adjustments will aid in the following areas:

• Host filtering
• Identity group management
• Total user count accuracy
• Debug settings

Configuration Instructions

• Select Target Hosts and Exclude Groups

  • Determine the host list you want to target, for example staging.adopter.com, production.adopter.com.
  • Identify groups to be excluded from the total user count.

  Benefit

  • Accurately select the target host list.

• HostFilter URLs

  • Include the necessary host filter URLs in your configuration to ensure the correct information is displayed. You can set this by environment via your different app-config files so in staging you see only Insights data captured in the staging environment.
  • NOTE: if you have set your hostFilter properly, but don’t see any data in your Insights dashboard, your firewall / internal network settings are likely stripping out the host metadata before the POST is sent to the Spotify Insights service. Contact your internal network team to help troubleshoot a possible solution. If that’s not possible, our recommendation is to set debug: true for all non-production environments to prevent data capture from lower-level interactions and testing and NOT use the hostFilter config.

  Benefit

  • Display the correct information related to host filters.

• Identify Groups filter

  • Specify the identity groups filter relevant to your environment to ensure the data captured displays the right teams.

  Benefit

  • Ensure that the captured data reflects the right teams (identity groups).

• Total User Filter

  • Adjust the settings to accurately reflect the total user count after exclusions.

  Benefit

  • Exclude specific groups from the total user count.

• Debug setting

  • Prevent data capture in specific environments. If debug is set to true, no data will be sent to the Spotify Insights server, but will be logged out in your browser console. This data is not stored anywhere, so those events are not tracked, will not persist, and cannot be aggregated.

Summary

By following these instructions, you will configure your Insights plugin effectively, ensuring that it provides the most accurate and useful data for your Backstage instance. Please note that it takes 1-2 days for data to populate. To verify the accuracy of the data being collected after this duration, it's recommended to check the Insights dashboard is showing the expected data and teams.