Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Plugins Guides
Bugsnag logo

Backstage Bugsnag Plugin

Created by Roadie

Bugsnag helps teams see and fix application errors fast. It collects exceptions from web, mobile, and backend apps, groups them, and shows the impact on users. Engineers use it to spot regressions, track stability, and decide what to fix first.

The Bugsnag plugin for Backstage brings that context into your developer portal. On each service page you get a Bugsnag tab with a focused errors table. You can scan recent errors, read key details, filter by attributes, and jump to the full report in Bugsnag when you need more depth. This keeps triage close to your code, docs, and ownership info in Backstage. It reduces app switching during incidents and reviews.

The plugin links Backstage components to Bugsnag projects using simple catalog annotations. It understands multiple stages such as production or staging. It is built to handle pagination limits in the Bugsnag API, so it shows a clear list of errors rather than heavy trend charts. You can still follow links to see trends in Bugsnag when you need them.

Common use cases include on call triage, release checks after deploys, and surfacing health signals during service reviews. If your teams already rely on Bugsnag for stability, this plugin makes that signal available where engineers work every day in Backstage.

Service errors overview inside a Bugsnag plugin.

Installation Instructions

These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.

Install the frontend package

  1. Change into your app package
Copy 
cd packages/app
  1. Add the plugin
Copy 
yarn add @roadiehq/backstage-plugin-bugsnag

Configure the proxy and plugin settings

  1. Open app-config.yaml in the repo root
  2. Add a proxy entry and optional settings
Copy 
proxy:
  '/bugsnag/api':
    target: 'https://api.bugsnag.com'
    headers:
      Authorization: 'token ${BUGSNAG_PERSONAL_TOKEN}'
      X-version: '2'

bugsnag:
  # optional
  # resultsPerPage controls the per_page query to Bugsnag
  # omit to use the default value of 30
  resultsPerPage: 50

Add the component to your entity page

  1. Open packages app src components catalog EntityPage.tsx
  2. Import the table component and add a route so users can find it
Copy 
// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import { EntityBugsnagErrorsOverviewTable } from '@roadiehq/backstage-plugin-bugsnag';

const serviceEntityPage = (
  <EntityLayoutWrapper>
    {/* other routes */}
    <EntityLayout.Route path="/bugsnag" title="Bugsnag">
      <EntityBugsnagErrorsOverviewTable />
    </EntityLayout.Route>
    {/* other routes */}
  </EntityLayoutWrapper>
);

export default serviceEntityPage;

Place this inside the page definition that you use for Service entities so it shows up under the Bugsnag tab when you run the app

Add the Bugsnag annotations to your catalog entity

Add this to catalog info yaml for each service that should show Bugsnag data. Use full names, not slugs

Copy 
metadata:
  annotations:
    bugsnag.com/project-key: your organization name/your project name

Provide the Bugsnag token to the backend

Set an environment variable for the backend process. The value must start with the word token followed by your personal auth token from Bugsnag

Copy 
# example for local development
# file packages/backend/.env
BUGSNAG_PERSONAL_TOKEN="token your token here"

Restart the backend after setting the variable

Backend setup for the proxy

The plugin fetches data through the Backstage proxy. Most apps already include the proxy backend. If your app does not have it, add it using the instructions for your backend system

Old backend system

  1. Add the proxy backend package if missing
Copy 
cd packages/backend
yarn add @backstage/plugin-proxy-backend
  1. Create the proxy plugin file if missing
Copy 
// packages/backend/src/plugins/proxy.ts
import { createRouter } from '@backstage/plugin-proxy-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,
  });
}
  1. Wire it up in the backend index file
Copy 
// packages/backend/src/index.ts
import proxy from './plugins/proxy';

// inside the main bootstrap function where other routers are added
const proxyRouter = await proxy(env);
apiRouter.use('/proxy', proxyRouter);

New backend system

  1. Add the proxy backend package if missing
Copy 
cd packages/backend
yarn add @backstage/plugin-proxy-backend @backstage/backend-defaults
  1. Register the proxy plugin
Copy 
// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';
import { proxyPlugin } from '@backstage/plugin-proxy-backend';

const backend = createBackend();

// register other plugins here

backend.add(proxyPlugin());

backend.start();

How the pieces fit together

  • The frontend table component reads data from the Backstage proxy path you set under proxy in app config
  • The backend proxy forwards those calls to the Bugsnag API with the headers you configured
  • The annotation on each entity tells the plugin which organization and project to query

Note on rate limits from Bugsnag
The table does not show error trends to avoid hitting the Bugsnag API rate limits. You can follow links from the table to Bugsnag for deeper details

Things to Know

How to use Bugsnag plugin in Backstage:

Firstly, add an annotation to the yaml config file of a component:

Copy 
bugsnag.com/project-key: <organization-name>/<project-notifier-api-key>

Both values can be found in Bugsnag settings dashboard, under organization and project settings.

Afterwards, proceed with adding your Bugsnag personal auth token to the environment variables of your backstage backend server (you can find it in https://app.bugsnag.com/settings/{organizationaname}/my-account/auth-tokens), in the form of the word ‘token’ followed by your token. So it should look like this:

Copy 
BUGSNAG_PERSONAL_TOKEN="token <your-api-key>"

Alternatively, if you are running backstage locally, you can provide the variable by the command

Copy 
env BUGSNAG_PERSONAL_TOKEN="token <your-api-key>" yarn dev

API Rate Limit in Bugsnag:

Since Bugsnag has a policy around API rate limits (https://bugsnagapiv2.docs.apiary.io/#introduction/rate-limiting), we are not displaying error trends in the table. However, you can visit error details page in Bugsnag for more details, including error trend.

Changelog

This changelog is produced from commits made to the Bugsnag 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.

Maintenance

  • Upgrade Bugsnag plugin to Backstage 1.40 to keep it current #1952 merged 2 months ago
  • Remove unused dependencies from the Bugsnag plugin #1847 merged 7 months ago
  • Revert a dependency bump to restore stability in the Bugsnag plugin #1825 merged 7 months ago
  • Update Backstage dependencies for the Bugsnag plugin #1821 merged 7 months ago
  • Update Backstage package versions for better compatibility #1728 merged 10 months ago
  • Routine dependency updates for the Bugsnag plugin #1684 merged 12 months ago

Breaking changes

None

Set up Backstage in minutes with Roadie

Get a demo