DORA Metrics Frontend Plugin for Backstage

This plugin provides a dashboard for visualizing DORA (DevOps Research and Assessment) metrics in your Backstage application. It integrates with Apache DevLake as a data source to display key DevOps performance indicators.

Note: Version 0.1.3+ includes pre-compiled TypeScript with declaration files for seamless integration with Backstage apps.

Features

• Display key DORA metrics:
  • Deployment Frequency
  • Lead Time for Changes
  • Mean Time to Restore
  • Change Failure Rate
• Interactive charts and visualizations
• Performance level indicators (Elite, High, Medium, Low)
• Time range selection for metrics analysis
• Project selection for multi-project environments
• Trend indicators showing improvement or decline

Prerequisites

• Backstage app version 1.0.0 or higher
• Apache DevLake instance with DORA metrics data
• Backend plugin @enginuity-io/dora-metrics-backend installed

Installation

# From your Backstage root directory
yarn add --cwd packages/app @enginuity-io/dora-metrics

Configuration

Add the following to your app-config.yaml:

doraMetrics:
  # URL to the backend API (default: /api/dora-metrics)
  backendUrl: /api/dora-metrics
  
  # Optional: Additional API path to append to backendUrl
  apiPath: ''
  
  # Optional: Frontend URL for CORS configuration
  frontendUrl: http://localhost:3000
  
  # Database configuration for backend
  database:
    connection:
      host: localhost      # DevLake database host
      port: 3306           # DevLake database port
      user: devlake        # Database user
      password: devlake    # Database password
      database: devlake    # Database name

Usage

Register the plugin in your Backstage app

Option 1: Using the new frontend plugin system (recommended)

1. Add the plugin to your app's packages/app/src/App.tsx:

import { doraMetricsPlugin } from '@enginuity-io/dora-metrics';

// Inside your FlatRoutes component:
<Route path="/dora-metrics" element={<DoraMetricsPage />} />

// Add to your plugins list
const app = createApp({
  apis,
  plugins: [
    // ... other plugins
    doraMetricsPlugin,
  ],
});

2. Add a link to the sidebar in packages/app/src/components/Root/Root.tsx:

import ExtensionIcon from '@material-ui/icons/Extension';

// Inside your SidebarPage component:
<SidebarItem icon={ExtensionIcon} to="dora-metrics" text="DORA Metrics" />

Option 2: Using the legacy plugin system

1. Add the plugin to your app's packages/app/src/plugins.ts:

export { doraMetricsPlugin } from '@enginuity-io/dora-metrics';

2. Add the page to your app's packages/app/src/App.tsx:

import { DoraMetricsPage } from '@enginuity-io/dora-metrics';

// Inside your AppRouter or similar component:
<Route path="/dora-metrics" element={<DoraMetricsPage />} />

3. Add a link to the sidebar in packages/app/src/components/Root/Root.tsx:

import ExtensionIcon from '@material-ui/icons/Extension';

// Inside your SidebarPage component:
<SidebarItem icon={ExtensionIcon} to="dora-metrics" text="DORA Metrics" />

Complete Integration

For complete integration, you need to install and configure both the frontend and backend plugins. Here's a step-by-step guide for both the new plugin system (recommended) and the legacy plugin system.

Using the New Plugin System (Backstage 1.15+)

1. Install both plugins:

# From your Backstage root directory
yarn add --cwd packages/app @enginuity-io/dora-metrics
yarn add --cwd packages/backend @enginuity-io/dora-metrics-backend

2. Register the frontend plugin in packages/app/src/App.tsx:

import { doraMetricsPlugin } from '@enginuity-io/dora-metrics';
import { DoraMetricsPage } from '@enginuity-io/dora-metrics';

// Inside your FlatRoutes component:
<Route path="/dora-metrics" element={<DoraMetricsPage />} />

// Add to your plugins list
const app = createApp({
  apis,
  plugins: [
    // ... other plugins
    doraMetricsPlugin,
  ],
});

3. Register the backend plugin in packages/backend/src/index.ts:

import { doraMetricsPlugin } from '@enginuity-io/dora-metrics-backend';

// Inside your backend.add() calls:
backend.add(doraMetricsPlugin);

4. Add the configuration to your app-config.yaml as described in the Configuration section.

Using the Legacy Plugin System

1. Install both plugins:

# From your Backstage root directory
yarn add --cwd packages/app @enginuity-io/dora-metrics
yarn add --cwd packages/backend @enginuity-io/dora-metrics-backend

2. Register the frontend plugin as described in the "Option 2: Using the legacy plugin system" section above.

3. Register the backend plugin in packages/backend/src/plugins/dora-metrics.ts:

import { createRouter } from '@enginuity-io/dora-metrics-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,
  });
}

4. Import and use the plugin in packages/backend/src/index.ts:

import doraMetrics from './plugins/dora-metrics';

// Inside the main function:
const doraMetricsEnv = useHotMemoize(module, () => createEnv('dora-metrics'));
apiRouter.use('/dora-metrics', await doraMetrics(doraMetricsEnv));

5. Add the configuration to your app-config.yaml as described in the Configuration section.

Development

# From your Backstage root directory
yarn start # Starts both frontend and backend

Testing

To test the plugin in isolation before integrating with Backstage:

# From the plugin directory
yarn test

You can also use the standalone test app in the repository:

# From the test-app directory
yarn install
yarn start

Publishing to npm

To publish the package to npm:

# From the plugin directory
yarn build
npm login  # Login to your npm account
npm publish --access public  # For scoped packages

API Reference

DoraMetricsPage Component

Main component that renders the DORA metrics dashboard.

import { DoraMetricsPage } from '@enginuity-io/dora-metrics';

<DoraMetricsPage />

Configuration API

The plugin reads configuration from the Backstage app-config.yaml file using the @backstage/config package.

Troubleshooting

• No data displayed: Ensure your Apache DevLake instance is properly configured and contains DORA metrics data
• Connection errors: Check the database connection settings in your app-config.yaml
• CORS issues: Verify that the frontendUrl in your configuration matches your actual frontend URL

Links

• Backstage Plugin Documentation
• DORA Metrics Information
• Apache DevLake Documentation
• npm Package