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.
Installation Instructions
These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.
Install the frontend package
- From the packages app directory run
yarn add @roadiehq/backstage-plugin-datadog
Wire it into the classic frontend
-
Open packages app src components catalog EntityPage.tsx
-
Import the plugin parts
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';
- Add the Datadog graph card to the overview content
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>
);
- Add a Datadog tab so users can view dashboards
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.
-
Open packages app src App.tsx
-
Import the feature from the alpha path and add it to features
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.
- Set your Datadog site if you do not use the default datadoghq.eu
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: sample-service
annotations:
datadoghq.com/site: datadoghq.com
spec:
type: service
owner: team-a
lifecycle: production
- 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.
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
- Show multiple dashboards
Use a comma separated list in the same annotation.
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
- 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.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: sample-service
annotations:
datadoghq.com/graph-token: eyJfX2VtYmVkX3Rva2VuIjoiZXhhbXBsZSJ9
spec:
type: service
owner: team-a
lifecycle: production
- Optional change the embedded graph size
Allowed values are small or medium or large or x large. Default is medium.
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:
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
- Login to your Datadog account and navigate to your dashboard list
- Select the dashboard you want to embed from the dashboard list (hover over “Dashboards” in the left navigation)
- Open sharing settings by clicking the settings cog icon on the right side of the dashboard
- Copy the public URL from the sharing textbox - this URL allows public access to your dashboard
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:
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
- Navigate to any dashboard containing the graph you want to embed
- Click the pencil icon (edit) on the graph widget you want to share
- Access sharing options by clicking the “Share” tab in the graph editor
- Configure display settings including timeframe, graph size, and legend preferences
- Generate the embed code by clicking “Generate embedded code”
- Copy the token from the generated code (highlighted portion in the sharing dialog)
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 cardsmedium
- Default size, good for most use caseslarge
- Expanded view with more detailx-large
- Maximum size for detailed analysis
If no size is specified, graphs default to medium
.
Step 3: Add graph annotations to your service
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:
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
:
# 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:
<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, and based on the code located here. 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
Focus on using Backstage, rather than building and maintaining it.