Backstage Umami Analytics Plugin

Umami is an open source, privacy focused web analytics tool that you can run on your own stack. It captures page views and custom events with a small script. Many teams use it to understand usage without heavy tracking.

The Umami Analytics Backstage plugin connects your portal to your Umami server through the Backstage Analytics API. It forwards the key events that Backstage already emits. Navigation shows up as page views in Umami. Other actions such as click, search, create, discover, and not found are sent as events. You get a clear picture of which pages people visit, which plugins see traffic, and where users drop off.

The plugin can track distinct users through Backstage identity. When enabled, it includes the Backstage entity ref as an identifier in each payload. This makes it easier to follow journeys across sessions and devices in Umami, while keeping instrumentation simple.

Common use cases include measuring adoption of new plugins, spotting broken or unused routes, learning which docs get attention, and tracking the impact of releases over time. During local work you can enable test mode to avoid sending data, turn on debug logs for visibility, or exclude your own visits. The goal is to help you make small, data informed changes that improve your developer portal.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the package

Copy

yarn --cwd packages/app add @axis-backstage/plugin-analytics-module-umami

Register the analytics API in the frontend

Add the Umami analytics module in your app APIs file.

Copy

// packages/app/src/apis.ts
import {
  AnyApiFactory,
  createApiFactory,
  analyticsApiRef,
  configApiRef,
  fetchApiRef,
  identityApiRef,
} from '@backstage/core-plugin-api';
import { UmamiAnalytics } from '@axis-backstage/plugin-analytics-module-umami';

export const apis: AnyApiFactory[] = [
  createApiFactory({
    api: analyticsApiRef,
    deps: {
      configApi: configApiRef,
      fetchApi: fetchApiRef,
      identityApi: identityApiRef, // optional but recommended for distinct user tracking
    },
    factory: ({ configApi, fetchApi, identityApi }) =>
      UmamiAnalytics.fromConfig(configApi, { fetchApi, identityApi }),
  }),
];

This replaces or augments any other analytics module you might have set up in the same file.

There are no visual components to add to routes. This module runs in the browser and listens for analytics events.

Configure app config

Add your Umami settings in your main app config file.

Copy

# app-config.yaml
app:
  analytics:
    umami:
      dataDomain: https://umami.organization.com
      trackingId: edo7byeh-ca66-461d-b2d5-78b71bdcl667

Distinct user tracking works when the identity API is provided in the apis setup. The plugin will include the Backstage user entity ref in the event payload.

Optional local settings

You can keep analytics off in local runs and print debug logs.

Copy

# app-config.local.yaml
app:
  analytics:
    umami:
      testMode: true
      debug: true

You can exclude your own visits in the browser with local storage.

Copy

// In the browser console
localStorage.setItem('umami.disabled', 'true');

What the plugin tracks

Navigation events become Umami page views
Other events like click or discover become Umami events

Backstage core emits these events. The module forwards them to your Umami instance based on your config.

Changelog

This changelog is produced from commits made to the Umami Analytics plugin since a year ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Features

Add distinct user tracking using Backstage identity #328 11 days ago
Exclude own visits when local storage key umami.disabled is set #313 1 month ago

Maintenance

Update to Backstage 1.42 for compatibility #319 1 month ago
Update to Backstage 1.40 #295 2 months ago
Update to Backstage 1.36.1 #259 7 months ago
Dependency updates #267 7 months ago

Documentation

Fix missing import in the README for Umami setup #213 10 months ago

Breaking changes

None

Set up Backstage in minutes with Roadie

Focus on using Backstage, rather than building and maintaining it.

Get a demo