WhitepaperSelf-hosting Backstage vs managed Backstage
Roadie
← Backstage Plugins Guides
Grafana logo

Backstage Grafana Plugin

The Backstage Grafana plugin lists Grafana alerts and dashboards.

Created by K-Phoen

Available on Roadie

Set up Backstage in minutes with Roadie

Get a demo

Installation steps

Install the plugin into your Backstage instance.

yarn --cwd packages/app add @k-phoen/backstage-plugin-grafana

Create an API key if you don't already have one. Grafana docs can be found <a href='https://grafana.com/docs/grafana/latest/developers/http_api/auth/#create-api-token' target="_blank>here.

Add proxy and Grafana configuration to the app-config.yaml file in the root directory.

# app-config.yaml
proxy:
  '/grafana/api':
    # May be a public or an internal DNS
    target: https://grafana.host/
    headers:
      Authorization: Bearer ${GRAFANA_TOKEN}

grafana:
  # Publicly accessible domain
  domain: https://monitoring.company.com

  # Is unified alerting enabled in Grafana?
  # See: https://grafana.com/blog/2021/06/14/the-new-unified-alerting-system-for-grafana-everything-you-need-to-know/
  # Optional. Default: false
  unifiedAlerting: false
    ...

Add the EntityGrafanaAlertsCard card to display alerts on a component page.

// packages/app/src/components/catalog/EntityPage.tsx
import {
  EntityGrafanaAlertsCard,
} from '@k-phoen/backstage-plugin-grafana';

// ...

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    <Grid item md={6}>
      <EntityAboutCard variant="gridItem" />
    </Grid>

    <Grid item md={6}>
      {/* Grafana alert card start */}
      <EntityGrafanaAlertsCard />
      {/* Grafana alert card end */}
    </Grid>

    <Grid item md={4} xs={12}>
      <EntityLinksCard />
    </Grid>
    <Grid item md={8} xs={12}>
      <EntityHasSubcomponentsCard variant="gridItem" />
    </Grid>
  </Grid>
);

Add the EntityGrafanaDashboardsCard component to display dashboards on a component page.

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

import {
  EntityGrafanaDashboardsCard,
} from '@k-phoen/backstage-plugin-grafana';

// ...

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    <Grid item md={6}>
      <EntityAboutCard variant="gridItem" />
    </Grid>

    <Grid item md={6}>
      {/* Grafana alert card start */}
      <EntityGrafanaDashboardsCard />
      {/* Grafana alert card end */}
    </Grid>

    <Grid item md={4} xs={12}>
      <EntityLinksCard />
    </Grid>
    <Grid item md={8} xs={12}>
      <EntityHasSubcomponentsCard variant="gridItem" />
    </Grid>
  </Grid>
);

Add the EntityOverviewDashboardViewer component to embed dashboards on a page

// packages/app/src/components/catalog/EntityPage.tsx
import {
  EntityGrafanaDashboardsCard,
} from '@k-phoen/backstage-plugin-grafana';

// ...

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    <Grid item md={6}>
      <EntityAboutCard variant="gridItem" />
    </Grid>

    <Grid item md={6}>
      {/* Grafana overview dashboard embed start */}
      <EntityOverviewDashboardViewer />
      {/* Grafana overview dashboard embed end */}
    </Grid>

    <Grid item md={4} xs={12}>
      <EntityLinksCard />
    </Grid>
    <Grid item md={8} xs={12}>
      <EntityHasSubcomponentsCard variant="gridItem" />
    </Grid>
  </Grid>
);

Update relevant catalog-info.yaml files to include grafana annotations.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  annotations:
    grafana/alert-label-selector: "service=awesome-service"
    grafana/dashboard-selector: "(tags @> 'my-service' || tags @> 'my-service-slo') && tags @> 'generated'"
    grafana/overview-dashboard: 'http://grafana/d/qSfS51a4z/some-dashboard?orgId=1&kiosk'
  name: my-entity
  namespace: default
spec:
  # …

Found a mistake? Update these instructions.

Things to know

Useful info

For the dashboard-selector a series of variables as well as binary and unary operators are supported.

Supported variables:

  • title: title of the dashboard
  • tags: array of tags defined by the dashboard
  • url: URL of the dashboard
  • folderTitle: title of the folder in which the dashboard is defined
  • folderUrl: URL of the folder in which the dashboard is defined

Supported binary operators:

  • ||: logical or
  • &&: logical and
  • ==: equality (=== operator in Javascript)
  • !=: inequality (!== operator in Javascript)
  • @>: inclusion (left.includes(right) in Javascript)

Supported unary operators:

  • !: logical negation

Set up Backstage in minutes with Roadie

Get a demo