Backstage Airbrake Plugin

Airbrake is an error tracking service that collects exceptions from your apps and groups them for review. It helps teams see where failures happen, what changed, and how often issues repeat.

The Airbrake plugin brings that context into Backstage. It connects your catalog to the matching Airbrake projects so engineers can see recent errors right on the service page. You get a focused view of the latest notices and trends, with quick links to dig deeper in Airbrake when needed. The plugin is maintained in the Backstage community plugins repo, which makes it easy to discover and keep up to date.

Common use cases are simple. Cut context switching during triage. Spot spikes after a release. Compare noise across services to find hotspots. Keep ownership clear by showing error signals next to docs and on call info in one place. The backend supports Backstage’s newer backend system, so it fits well in modern instances and keeps pace with the platform.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the packages

Copy

# from your Backstage root directory
yarn --cwd packages/app add @backstage-community/plugin-airbrake
yarn --cwd packages/backend add @backstage-community/plugin-airbrake-backend

Add the frontend to your Entity page

Edit packages/app/src/components/catalog/EntityPage.tsx

Import the components

Copy

import {
  EntityAirbrakeContent,
  isAirbrakeAvailable,
} from '@backstage-community/plugin-airbrake';

Add a route on each entity page where you want the Airbrake tab

Copy

const serviceEntityPage = (
  <EntityLayoutWrapper>
    {/* other routes */}
    <EntityLayout.Route
      if={isAirbrakeAvailable}
      path="/airbrake"
      title="Airbrake"
    >
      <EntityAirbrakeContent />
    </EntityLayout.Route>
  </EntityLayoutWrapper>
);

const websiteEntityPage = (
  <EntityLayoutWrapper>
    {/* other routes */}
    <EntityLayout.Route
      if={isAirbrakeAvailable}
      path="/airbrake"
      title="Airbrake"
    >
      <EntityAirbrakeContent />
    </EntityLayout.Route>
  </EntityLayoutWrapper>
);

const defaultEntityPage = (
  <EntityLayoutWrapper>
    {/* other routes */}
    <EntityLayout.Route
      if={isAirbrakeAvailable}
      path="/airbrake"
      title="Airbrake"
    >
      <EntityAirbrakeContent />
    </EntityLayout.Route>
  </EntityLayoutWrapper>
);

If your file uses EntityLayout directly, place the route inside that layout. The key parts are the import above and the EntityLayout.Route block.

Add the backend

New backend system

Edit packages/backend/src/index.ts

Copy

import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// add your other features here

backend.add(import('@backstage-community/plugin-airbrake-backend'));

backend.start();

Legacy backend system

Create a backend plugin module

packages/backend/src/plugins/airbrake.ts

Copy

import { createRouter } from '@backstage-community/plugin-airbrake-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  return await createRouter({
    logger: env.logger,
    config: env.config,
    discovery: env.discovery,
    tokenManager: env.tokenManager,
  });
}

Wire it up in your backend

Edit packages/backend/src/index.ts

Copy

import airbrake from './plugins/airbrake';

// inside your main bootstrap function

const airbrakeEnv = useHotMemoize(module, () => createEnv('airbrake'));

apiRouter.use('/airbrake', await airbrake(airbrakeEnv));

Your file likely already defines createEnv and apiRouter. Match the pattern used for your other legacy backend plugins.

Add config

Edit app-config.yaml

Copy

airbrake:
  apiKey: ${AIRBRAKE_API_KEY}

Set environment variable AIRBRAKE_API_KEY before starting the backend

Copy

export AIRBRAKE_API_KEY=your_airbrake_api_key

Annotate catalog entities

Add the Airbrake project id to each entity that should show the Airbrake tab

catalog-info.yaml

Copy

metadata:
  annotations:
    airbrake.io/project-id: '123456'

Changelog

This changelog is produced from commits made to the Airbrake plugin since a year ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Deprecations

Airbrake

Deprecate the legacy backend #2041 merged 10 months ago

Maintenance

Airbrake

Remove backend common from Airbrake #2446 merged 9 months ago
If your app relied on backend common through this plugin you may need to add it directly
Remove unused canvas dev dependency #3565 merged 6 months ago
Reduce knip false positives by updating repo tools #3018 merged 7 months ago
No runtime impact

Set up Backstage in minutes with Roadie

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

Get a demo