@enginuity-io/dora-metrics/README.md

DORA Metrics frontend plugin for Backstage

# 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](https://www.npmjs.com/package/@enginuity-io/dora-metrics-backend) installed

## Installation

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

## Configuration

Add the following to your `app-config.yaml`:

```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`:

```typescript
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`:

```typescript
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`:

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

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

```typescript
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`:

```typescript
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:
```bash
# 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`:
```typescript
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`:
```typescript
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:
```bash
# 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`:
```typescript
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`:
```typescript
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

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

## Testing

To test the plugin in isolation before integrating with Backstage:

```bash
# From the plugin directory
yarn test
```

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

```bash
# From the test-app directory
yarn install
yarn start
```

## Publishing to npm

To publish the package to npm:

```bash
# 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.

```typescript
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](https://backstage.io/docs/plugins/structure-of-a-plugin)
- [DORA Metrics Information](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance)
- [Apache DevLake Documentation](https://devlake.apache.org/docs/Overview/Introduction)
- [npm Package](https://www.npmjs.com/package/@enginuity-io/dora-metrics)