Datadog UI Extensions

What is a UI Extension?

UI Extensions enable developers to extend the native functionality of Datadog through custom dashboard widgets. For example, if there is a data visualization you want that Datadog does not support, or a common remediation workflow you execute in a third-party platform, you could write a UI Extension to extend this functionality within Datadog.

Setup

Set up your local development environment

  1. Create a Datadog app for your UI Extension:

    yarn create @datadog/app

  2. Navigate to the folder you have created:

    cd starter-kit

  3. Set up your development environment:

    yarn start

This starts your local development server on http://localhost:3000/.

If you see the following message, your application is running:

The application controller is running in the background

Note that there are two pages:

  • http://localhost:3000: A main controller that orchestrates all of your different extensions (such as widgets, menus, or modals). It will come in handy as you enrich app functionality.
  • http://localhost:3000/widget: Components for widgets, modals, or anything that needs a dedicated display.

See the Developer Platform Developer Guide for details about this architecture.

You may notice an uncaught HandshakeTimeoutError in your JavaScript Console when you interact with the local widget in your browser directly. This is expected. The Datadog Apps SDK is designed to run in an iframe that connects to the Datadog User Interface and the handshake attempt between the widget and the Datadog UI will timeout when there is no Datadog UI for the SDK has to communicate with.

Add your app to the Developer Platform

  1. Navigate to Integrations > Developer Platform and click + New App. Add a new app to the developer platform

  2. Enter a unique name for your application.

  3. Optionally, once you’re presented with the dashboard for your new application, you can change the app name, give the app a more detailed description, or change its icon. Edit app information from the app dashboard

Add your app to a dashboard

  1. Before you can add your app to a dashboard, you must enable it by clicking on UI Extensions. App Edit Enable UI Extensions

    Once this view loads, click on the Enable UI Extensions button.

  2. Once you’re presented with more options for your app, change the Root URL and Debug Mode Root URL to match the localhost version of the widget you’re running. The main controller path is /widget. These URL values will change as you build your application and begin to host it on your own infrastructure.

  3. Turn the toggle to Dashboard Custom Widget on. This generates JSON for the app.

    App Edit UI Extensions

    In this example, the JSON output contains a value called Your first widget. This is the name of your widget as it appears in the menu to add to your Dashboards.

  4. Navigate to your dashboard and add a widget.

    Add widget to your Dashboard

  5. The Custom Widgets section is at the bottom of the sidebar. Find your widget in the list and add it to your dashboard.

    Add your widget from the custom widgets section

  6. A preview of your new widget appears, along with some options. Scroll down and click Done to add it to your dashboard.

    Click Done to add your widget to the dashboard

  7. To build your application, run yarn build in your terminal. Then, move your static generated site to the hosting platform of your choice and update the URLs in the app settings.

OAuth API Access

When OAuth API Access is enabled, users need to be authenticated before using the app. This feature allows you to integrate your existing authentication mechanism (for example, cookie-based username and password login) with the Developer Platform.

Sample Applications

Further reading