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

Backstage Datadog Plugin

Created by Roadie

Datadog is an observability platform for modern apps. It brings metrics, logs, traces, and dashboards into one place so teams can watch system health and respond fast. It is widely used across cloud and hybrid environments.

The Datadog plugin brings that context into Backstage. You can surface live Datadog dashboards in a dedicated tab for each service. You can add focused graphs on the overview so owners see key signals without leaving the portal. It supports multiple dashboards for a single component, and you can choose graph sizes that fit your layout. This reduces tab switching during incidents and standups, and keeps context when you triage or review reliability work.

If you want a quick summary in one sentence Datadog describes the integration this way, “This integration enables you to embed Datadog graphs and dashboards into your Backstage instance.”

One note on security. Shared dashboards and graphs use public URLs. Treat those links with care in your catalog metadata.

A screenshot of the Datadog 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. From the packages app directory run
Copy 
yarn add @roadiehq/backstage-plugin-datadog

Wire it into the classic frontend

  1. Open packages app src components catalog EntityPage.tsx

  2. Import the plugin parts

Copy 
import React from 'react';
import { Grid } from '@mui/material';
import { EntityLayout, EntitySwitch } from '@backstage/plugin-catalog';
import {
  EntityDatadogContent,
  EntityDatadogGraphCard,
  isDatadogGraphAvailable,
} from '@roadiehq/backstage-plugin-datadog';
  1. Add the Datadog graph card to the overview content
Copy 
const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {/* your other cards */}
    <EntitySwitch>
      <EntitySwitch.Case if={isDatadogGraphAvailable}>
        <Grid item xs={12}>
          <EntityDatadogGraphCard />
        </Grid>
      </EntitySwitch.Case>
    </EntitySwitch>
  </Grid>
);
  1. Add a Datadog tab so users can view dashboards
Copy 
const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      {overviewContent}
    </EntityLayout.Route>

    <EntityLayout.Route path="/datadog" title="Datadog">
      <EntityDatadogContent />
    </EntityLayout.Route>
  </EntityLayout>
);

Place these in the same file where you define your service entity page. Most Backstage apps already have a serviceEntityPage or similar in EntityPage.tsx.

Use the new frontend system

If your app uses the new frontend system, enable the plugin feature. You do not need to place cards or tabs by hand.

  1. Open packages app src App.tsx

  2. Import the feature from the alpha path and add it to features

Copy 
import { createApp } from '@backstage/app-defaults';
import React from 'react';
import datadogPlugin from '@roadiehq/backstage-plugin-datadog/alpha';

export const app = createApp({
  features: [
    datadogPlugin,
  ],
});

The plugin will register its UI where it makes sense once the right annotations are present on entities.

Backend setup

No backend plugin is required. There is nothing to install for the legacy backend system or the new backend system.

Add entity annotations

Add these annotations to the catalog entity that should show Datadog content.

  1. Set your Datadog site if you do not use the default datadoghq.eu
Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  annotations:
    datadoghq.com/site: datadoghq.com
spec:
  type: service
  owner: team-a
  lifecycle: production
  1. Show one dashboard in the Datadog tab

Get a share link for your dashboard in Datadog. Copy the URL. Add it to the annotation below.

Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  annotations:
    datadoghq.com/dashboard-url: https://p.datadoghq.com/sb/abcdef
spec:
  type: service
  owner: team-a
  lifecycle: production
  1. Show multiple dashboards

Use a comma separated list in the same annotation.

Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  annotations:
    datadoghq.com/dashboard-url: https://p.datadoghq.com/sb/abc,https://p.datadoghq.com/sb/def
spec:
  type: service
  owner: team-a
  lifecycle: production
  1. Show an embedded graph on the overview tab

Get a graph embed token from your Datadog dashboard share dialog. Add it to the annotation below.

Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  annotations:
    datadoghq.com/graph-token: eyJfX2VtYmVkX3Rva2VuIjoiZXhhbXBsZSJ9
spec:
  type: service
  owner: team-a
  lifecycle: production
  1. Optional change the embedded graph size

Allowed values are small or medium or large or x large. Default is medium.

Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  annotations:
    datadoghq.com/graph-token: eyJfX2VtYmVkX3Rva2VuIjoiZXhhbXBsZSJ9
    datadoghq.com/graph-size: large
spec:
  type: service
  owner: team-a
  lifecycle: production

Where it shows in the UI

  • The graph card renders on the overview tab for entities that have a graph token annotation
  • The Datadog tab renders for entities that have a dashboard url annotation

Things to Know

Plugin Configuration and Usage

The Datadog plugin supports embedding both dashboards and individual graphs into your Backstage service pages. Configuration is done through annotations in your service’s catalog metadata file.

Authentication and Domain Configuration

The plugin uses Datadog’s public sharing URLs, which don’t require API authentication but do require properly configured sharing permissions in your Datadog account.

Specifying your Datadog domain

By default, the plugin uses datadoghq.eu as the domain. If your organization uses a different Datadog instance, specify it using the datadoghq.com/site annotation:

Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  description: |
    A sample service
  annotations:
    datadoghq.com/site: datadoghq.com  # or us3.datadoghq.com, us5.datadoghq.com, etc.

Common Datadog sites include:

  • datadoghq.com (US1)
  • datadoghq.eu (EU1)
  • us3.datadoghq.com (US3)
  • us5.datadoghq.com (US5)
  • ap1.datadoghq.com (AP1)

Embedding Datadog Dashboards

Datadog dashboards provide comprehensive views of your service’s health through multiple widgets and metrics. The plugin can display full dashboards directly within Backstage entity pages.

Step 1: Enable dashboard sharing in Datadog

  1. Login to your Datadog account and navigate to your dashboard list
  2. Select the dashboard you want to embed from the dashboard list (hover over “Dashboards” in the left navigation)
  3. Open sharing settings by clicking the settings cog icon on the right side of the dashboard

dashboard

  1. Copy the public URL from the sharing textbox - this URL allows public access to your dashboard

dashboard share

Step 2: Add dashboard annotation to your service

Add the dashboard URL to your service’s metadata file using the datadoghq.com/dashboard-url annotation:

Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  description: |
    A sample service for order processing
  annotations:
    datadoghq.com/site: datadoghq.com
    datadoghq.com/dashboard-url: "https://app.datadoghq.com/dashboard/abc-123-def"

The dashboard will appear in the dedicated Datadog tab of your service entity page, providing a full view of all dashboard widgets and metrics.

Embedding Individual Datadog Graphs

Individual graphs are useful when you want to highlight specific metrics (like response time or error rate) directly on your service’s overview page without displaying an entire dashboard.

Step 1: Generate a graph sharing token

  1. Navigate to any dashboard containing the graph you want to embed
  2. Click the pencil icon (edit) on the graph widget you want to share

dashboard

  1. Access sharing options by clicking the “Share” tab in the graph editor
  2. Configure display settings including timeframe, graph size, and legend preferences
  3. Generate the embed code by clicking “Generate embedded code”
  4. Copy the token from the generated code (highlighted portion in the sharing dialog)

dashboard

Step 2: Configure graph display options

You can customize how the graph appears in Backstage using the datadoghq.com/graph-size annotation:

  • small - Compact graph suitable for overview cards
  • medium - Default size, good for most use cases
  • large - Expanded view with more detail
  • x-large - Maximum size for detailed analysis

If no size is specified, graphs default to medium.

Step 3: Add graph annotations to your service

Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  description: |
    A sample microservice handling user authentication
  annotations:
    datadoghq.com/site: datadoghq.com
    datadoghq.com/graph-token: "your-graph-token-here"
    datadoghq.com/graph-size: large

The graph will appear as a card on your service’s overview page, allowing developers to quickly assess key metrics without leaving Backstage.

Advanced Configuration

Multiple graphs and dashboards

You can configure a single service to display both individual graphs and full dashboards by combining annotations:

Copy 
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: |
    Handles payment processing and fraud detection
  annotations:
    datadoghq.com/site: datadoghq.com
    # Display key metrics on overview page
    datadoghq.com/graph-token: "response-time-graph-token"
    datadoghq.com/graph-size: medium
    # Provide detailed monitoring dashboard
    datadoghq.com/dashboard-url: "https://app.datadoghq.com/dashboard/payment-dashboard"

Content Security Policy configuration

Your Backstage instance must allow embedding content from Datadog domains. Add the appropriate frame-src directives to your app-config.yaml:

Copy 
# app-config.yaml
backend:
  csp:
    frame-src:
      - "'self'"
      # Allow Datadog embedding for all major regions
      - "https://app.datadoghq.com"
      - "https://app.datadoghq.eu"
      - "https://us3.datadoghq.com"
      - "https://us5.datadoghq.com"
      - "https://ap1.datadoghq.com"

Conditional display with entity switches

The plugin provides isDatadogGraphAvailable and isDatadogDashboardAvailable conditionals to show Datadog content only when properly configured:

Copy 
<EntitySwitch>
  <EntitySwitch.Case if={isDatadogGraphAvailable}>
    <Grid item md={6}>
      <EntityDatadogGraphCard />
    </Grid>
  </EntitySwitch.Case>
</EntitySwitch>

Security Considerations

Important: Datadog sharing URLs are public and accessible by anyone who obtains the URL. This means:

  • Anyone with the dashboard or graph URL can view your monitoring data
  • URLs should be treated as sensitive information
  • Consider the data exposure when sharing dashboards that might contain business-sensitive metrics
  • Regularly audit and rotate sharing URLs if needed
  • Avoid embedding dashboards with personally identifiable information (PII) or sensitive business data

Ensure your team understands these implications before implementing Datadog embedding in your Backstage instance.

Changelog

This changelog is produced from commits made to the Datadog plugin since a year ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

  • #1727 Datadog content shows only on entities with the required annotations in the new frontend system. This changes the default visibility. 10 months ago

Documentation

  • #1727 Update docs to remove app config references. The new frontend system auto discovers Datadog content. 10 months ago

Maintenance

  • #1952 Upgrade Backstage to 1.40. 2 months ago
  • #1847 Remove unused plugin dependencies. 7 months ago
  • #1825 Revert a previous dependency update in plugins. 8 months ago
  • #1821 Update dependencies for plugins. 8 months ago
  • #1759 Move date handling to luxon. 9 months ago
  • #1728 Update Backstage package versions. 10 months ago
  • #1684 Update dependencies for plugins. 11 months ago

Set up Backstage in minutes with Roadie

Get a demo