Backstage Prometheus Plugin

The Backstage Prometheus plugin brings comprehensive monitoring capabilities directly into your developer portal. As a frontend plugin, it provides developers with immediate access to critical system metrics and alerts without requiring them to leave the Backstage interface.

Core Components

The plugin offers three main components that can be integrated into your entity pages:

1. Entity Content Page - A full-page view displaying comprehensive metrics and alerts
2. Alert Table Widget - A compact widget showing active Prometheus alerts in a tabular format
3. Graph Widget - Interactive visualizations supporting both line and area graph types

Key Capabilities

• Real-time Alert Monitoring: Display active alerts with state, value, labels, evaluation time, and annotations
• Interactive Metrics Visualization: View time-series data with hover details and customizable time ranges
• Multi-Instance Support: Connect to multiple Prometheus servers across different environments
• Flexible Query Support: Use individual metrics, PromQL queries, or Prometheus recording rules
• Dynamic Configuration: Configure graphs and alerts per entity using annotations

Entity Annotations

The plugin uses Backstage entity annotations to determine what monitoring data to display for each service. These annotations provide a flexible way to configure monitoring without code changes.

Metrics Visualization with prometheus.io/rule

The prometheus.io/rule annotation defines which metrics to display as graphs. It accepts a comma-separated list of queries or recording rules with optional grouping dimensions.

Syntax: prometheus.io/rule: query1|grouping_dimension,query2|grouping_dimension

The annotation supports three types of queries:

• Individual metrics: Simple metric names like node_memory_active_bytes
• PromQL queries: Complex expressions like sum by (instance) (node_cpu_seconds_total)
• Recording rules: References to predefined Prometheus recording rules like memUsage

Example annotation:

prometheus.io/rule: memUsage|component,node_memory_active_bytes|instance,sum by (instance) (node_cpu_seconds_total)

This produces three distinct graphs:

1. Recording Rule with Component Grouping memUsage|component creates an area graph grouped by the component label:

2. Memory Metrics with Instance Grouping node_memory_active_bytes|instance displays memory usage across instances with interactive hover details:

3. CPU Metrics from PromQL Query sum by (instance) (node_cpu_seconds_total) uses the query’s grouping dimension (instance) automatically:

Alert Management with prometheus.io/alert

The prometheus.io/alert annotation specifies which Prometheus alerts to display in a table format, showing state, value, labels, evaluation time, and annotations.

Example annotations:

### Display specific alerts
prometheus.io/alert: 'High CPU Usage,Memory Exhaustion'

### Display all configured alerts
prometheus.io/alert: all

Label-Based Alert Filtering with prometheus.io/labels

Use the prometheus.io/labels annotation to filter alerts by specific label values, useful for multi-tenant environments or when you want to show only relevant alerts.

Example:

prometheus.io/labels: "environment=production,service=api"

Multiple Prometheus Instances

The plugin supports connecting to multiple Prometheus instances, which is essential for organizations with separate monitoring setups for different environments or teams.

Configuration for Multiple Instances

Configure multiple proxy endpoints in your app-config.yaml:

proxy:
  '/prometheus/api':
    target: http://prod-prometheus:9090/api/v1/
  '/prometheus-staging/api':
    target: http://staging-prometheus:9090/api/v1/
  '/prometheus-dev/api':
    target: http://dev-prometheus:9090/api/v1/

prometheus:
  proxyPath: /prometheus/api
  uiUrl: http://prod-prometheus:9090

Using Service-Specific Instances

Specify which Prometheus instance an entity should use with the prometheus.io/service-name annotation:

### catalog-info.yaml
metadata:
  annotations:
    prometheus.io/service-name: staging
    prometheus.io/rule: api_requests_per_second|endpoint
    prometheus.io/alert: 'API High Latency'

Dynamic Proxying

For advanced scenarios, the plugin supports dynamic Prometheus proxying through backend middleware. This enables routing to different Prometheus instances based on entity metadata or other runtime conditions.

Backend Configuration

Install the backend plugin for dynamic routing:

cd packages/backend
yarn add @roadiehq/backstage-plugin-prometheus-backend

Configure dynamic routing in your backend:

// packages/backend/src/plugins/prometheus.ts
import { createRouter } from '@roadiehq/backstage-plugin-prometheus-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,
  });
}

This enables sophisticated routing scenarios where different entities can automatically connect to appropriate Prometheus instances based on their metadata or environment.

Custom Graphs and Tables

For advanced use cases requiring custom layouts or specialized functionality, the plugin exports individual components that can be used programmatically.

Custom Graph Component

Create custom graphs using the PrometheusGraph component:

import { PrometheusGraph } from '@roadiehq/backstage-plugin-prometheus';

// Custom graph with specific styling
<PrometheusGraph
  query="rate(http_requests_total[5m])"
  range={{ hours: 6 }}
  step={60}
  dimension="method"
  graphType="area"
/>

PrometheusGraph Props:

{
  query: string;                    // PromQL query to execute
  range?: {                        // Time range for the query
    hours?: number;
    minutes?: number;
  };
  step?: number;                   // Step size in seconds
  dimension?: string;              // Grouping dimension
  graphType?: 'line' | 'area';     // Graph visualization type
}

Custom Alert Table

Create specialized alert displays using the PrometheusAlertStatus component:

import { PrometheusAlertStatus } from '@roadiehq/backstage-plugin-prometheus';

// Custom alert table with specific alerts
<PrometheusAlertStatus
  alerts={['Critical CPU', 'Memory Warning']}
  onRowClick={(alert) => {
    // Custom click handler for alert rows
    window.open(`/prometheus/graph?query=${alert.expr}`);
  }}
/>

PrometheusAlertStatus Props:

{
  alerts: string[] | 'all';        // Alert names or 'all' for everything
  onRowClick?: (alert: Alert) => void; // Optional click handler
}

These components provide full flexibility for creating custom monitoring dashboards while leveraging the plugin’s core Prometheus integration functionality.

Features

• Add customisation support in the Prometheus plugin. You can add extra table columns. You can hide the annotations column. You can hide the labels column. Support multiple Prometheus instances. #1858 Merged 6 months ago

Maintenance

• Upgrade to 1.40 #1952 Merged 2 months ago
• Remove unused plugin dependencies #1847 Merged 6 months ago
• Revert dependency update #1825 Merged 7 months ago
• Update Backstage dependencies #1821 Merged 7 months ago
• Update Backstage package versions #1728 Merged 10 months ago
• Update dependencies #1684 Merged 11 months ago