@spotify/backstage-plugin-insights

Spotify Plugins for Backstage: Insights - Frontend

Backstage Insights helps you measure Backstage adoption, identify anomalous trends, and understand user behavior.

This plugin provides the frontend functionality for Insights.

Prerequisites

1. Complete Spotify plugin bundle setup

This package is a Backstage plugin and is part of the "Spotify Plugins for Backstage" bundle. For you to use this plugin, you must purchase a license key at https://backstage.spotify.com/. After purchasing a license key, follow the instructions on https://backstage.spotify.com/account before continuing.

2. Check your Backstage version

Please ensure your Backstage version matches the supported version shown under the installation instructions on https://backstage.spotify.com/account, and always check compatibility before updating Backstage.

3. Configure data collection

Backstage Insights relies on an implementation of the Plugin Analytics API to collect usage data; this analytics module is available under the package named @spotify/backstage-plugin-analytics-module-insights. Please ensure that you've installed this analytics module before proceeding.

Installation instructions for the analytics module are available on the @spotify/backstage-plugin-analytics-module-insights readme.

Installation

1. Getting the plugin

Add the Insights frontend as dependency to your Backstage frontend app:

yarn workspace app add @spotify/backstage-plugin-insights

2. Configure access controls

If you currently permission access to catalog resources, you'll likey want to configure who can access Insights as it could potentially expose information from the catalog that users might not normally have permissions to see.

The recommended approaches to setting access controls for this plugin require the Backstage permissions framework. You may have set up this up already when configuring other plugins from the Spotify bundle, but if not, follow this guide to setting up the permissions framework.

Option 1: Using the RBAC plugin (Recommended)

"The RBAC plugin is a no-code management UI for restricting access to plugins, routes, and data within Backstage. Admins can quickly define roles, assign users and groups, and configure permissions to encode authorization decisions according to your organization’s evolving security and compliance needs."

Using the RBAC plugin, it's easy to define access controls for Insights with the single insights.read permission:

For more information on how to make use of the RBAC plugin, click here.

Option 2: Using custom policy handlers

If you don't use the RBAC plugin, it's also possible to define custom handlers for permission framework policies.

// packages/backend/src/plugins/permissions.ts

class ExamplePolicy implements PermissionPolicy {
  async handle(request: PolicyQuery): Promise<PolicyDecision> {
    if (request.permission.name === 'insights.read') {
      const isAllowed = await someEvaluationFunction();

      if (isAllowed) {
        return {
          result: AuthorizeResult.ALLOW,
        };
      }
    }

    return { result: AuthorizeResult.DENY };
  }
}

3. Integrate the plugin with your frontend app

First install the Insights routes in the app within the packages/app/src/App.tsx. This will provide the UI for insights under the /insights route.

Insights links out to the Search plugin, so it also needs configuring to know the Search plugin has been routed under.

  // packages/app/src/App.tsx

+ import {
+   InsightsPage,
+   insightsPlugin,
+ } from '@spotify/backstage-plugin-insights';

    ...

// Configure the route location for the Search plugin inside bindRoutes
+ bindRoutes({ bind }) {
+   bind(insightsPlugin.externalRoutes, {
+     searchPageRouteRef: searchPlugin.routes.root,
+   });
+ }

    ...

  const routes = (
    <FlatRoutes>
      /* ... */
+     <Route path="/insights" element={<InsightsPage />} />
    </FlatRoutes>
  );

Insights also provides a sidebar item that will only be visible to users who have been given permissions to Insights (setup in the previous section). This is an optional step, but it provides an easy way for Insights authorized users to access the plugin.

  // packages/app/src/components/Root.tsx

+ import { InsightsSidebarItem } from '@spotify/backstage-plugin-insights';

export const Root = ({ children }: PropsWithChildren<{}>) => (
  <SidebarPage>
    <Sidebar>
      <SidebarLogo />

      /* ... */

      <SidebarScrollWrapper>
        <SidebarItem icon={MapIcon} to="tech-radar" text="Tech Radar" />
        <SidebarItem
          icon={SkillExchangeIcon}
          to="skill-exchange"
          text="Skill Exchange"
        />
        <SidebarItem icon={PulseIcon} to="pulse" text="Pulse" />
        <SidebarItem icon={SoundcheckIcon} to="soundcheck" text="Soundcheck" />
        <RBACSidebarItem />
+       <InsightsSidebarItem />
      </SidebarScrollWrapper>
    </Sidebar>
  </SidebarPage>
);

4. Check everything is working

Once access controls are set up correctly, users with the insights read permission should see a Insights sidebar menu item. Providing the Backend plugin has been setup and data has been collected for at least 48 hours, you should see data appear in the dashboards.