Upgrade your dashboards and tiles

We are phasing out the Custom chart functionality in favor of the new Data explorer, which greatly enhances your abilities to query and visualize metrics.

Overview

What: We have set a date to remove Custom charts from Dynatrace. If you use Custom charts, it's time to plan for upgrading your charts and dashboards to the Data explorer.
When:
- Dynatrace version 1.251+ offers web UI and API options for upgrading your charts and dashboards
- Dynatrace version 1.252+ offers a dashboard filtering option for quickly identifying dashboards that still need to be upgraded
- Dynatrace version 1.265, which is planned for release in Q2 2023, will be the last Dynatrace release to support Custom charts.
Why: With the Data explorer, we have significantly improved Dynatrace charting and dashboarding capabilities, and now have reached a stage where you can seamlessly move from the classic Custom charts to the Data explorer.
How: You can upgrade tile by tile, dashboard by dashboard, or all dashboards at once using the Dynatrace API.

For details, see below.

Does this apply to me?

This does not apply to visualizations and dashboards created using the Data explorer. This applies only to our old Custom chart functionality, which predated the Data explorer.

On the Dashboards page

Dynatrace version 1.252+

Starting with Dynatrace SaaS 1.252, you can filter the Dashboards page to list dashboards that should be upgraded (dashboards that have at least one old-style chart).

To see if you have any old-style charts to upgrade

In the Dynatrace menu, go to Dashboards.
optional To list only the dashboards that you own, add a filter for Ownership: Mine or Owner: <your-email-address>. There are two ways to set this filter:
- On the filter bar:
- In the quick settings panel on the left:
If you want to check all dashboards to which you have access, regardless of ownership, skip this step.
To list only the dashboards that have charts that need to be upgraded, add a filter for Custom charts: Yes.
Check the table
- If no dashboards are listed, you have nothing to upgrade. You can stop here.
- If you don't filter by dashboard ownership, you may see some preset dashboards with owner Dynatrace listed. You can ignore them. We will upgrade them soon.
- If any other dashboards are listed, they should each display the Custom charts label because you have set the Custom charts: Yes filter in the previous step. In the example below, you would have two dashboards to upgrade.

On the displayed dashboard

When you display a dashboard, there are two ways to see if it has any old-style charts that should be upgraded:

If a tile needs to be upgraded, it displays a warning icon and tooltip.
If the currently displayed dashboard has at least one tile that needs to be upgraded, the dashboard menu in the upper-right corner of the dashboard has an Upgrade option.

How can I upgrade?

Dynatrace version 1.251+

Before you do anything else, we recommend that you make backups of your most important dashboards. Then try to upgrade these backups so you get comfortable with the upgrading process before upgrading all of your remaining dashboards. For example, pick any popular dashboard in your environment that you depend on, one that has several advanced and complex Custom chart tiles (multiple metrics are used, and there are configurations for a unit, rates, etc.), and clone them. Then you can safely work on the clone and check whether everything upgrades correctly.

To list dashboards by popularity

In the Dynatrace menu, go to Dashboards.
This lists all dashboards you are permitted to view or edit.
Sort the table by the Popularity column.

To clone an existing dashboard

In the Dynatrace menu, go to Dashboards.
In the table of dashboards, select More (…) > Clone for the dashboard you want to copy.
- The copy opens in edit mode.
- The original dashboard is unaffected.

You can upgrade:

One tile at a time
One dashboard at a time (upgrade all tiles on a dashboard)
All using the Dynatrace API

Important: In all cases, make backups before starting, and try it out first to familiarize yourself with the process and make sure you finish the upgrade process by Dynatrace version 1.265. For details about the upgrade process after that point, see After Dynatrace version 1.265 below.

Upgrade via web UI

Dynatrace version 1.251+

In the Dynatrace web UI, you can upgrade one tile at a time or one dashboard at a time.

Upgrade one tile

To upgrade a single tile

Display a dashboard that has a tile that needs to be upgraded.
In the tile's menu, select Preview upgraded chart. The converted chart opens in the Data explorer in a new browser tab, so you can compare the old charts with the new visualizations.
Inspect the visualization to verify that it converted properly. Make changes as needed.
When you are satisfied with the conversion, select Pin to dashboard and pin the upgraded visualization to another dashboard or the same dashboard.
- If you pin it to the same dashboard, you will now have the old and new tiles on the same dashboard. This gives you another opportunity to compare the tiles. If you are satisfied with the results, delete the old tile (the one with the warning icon) and drag the new tile into its place.

Upgrade entire dashboard

You can run the following procedures with or without creating clones (backups).

Fast, no backup steps

To upgrade an entire dashboard (all tiles on the dashboard at once) without creating a clone (backup copy).

In the Dynatrace menu, go to Dashboards.
Find the dashboard in the table of dashboards.
In that dashboard's row, select > Upgrade. If no upgrade errors are encountered, the entire dashboard is upgraded.

Cautious, with backup steps

To create a clone (backup copy) of the dashboard and then upgrade the entire cloned dashboard (all tiles on the dashboard at once)

In the Dynatrace menu, go to Dashboards.
Find the dashboard in the table of dashboards.
In that dashboard's row, select > Clone. This creates a clone (copy) of the dashboard and opens it in edit mode. The original dashboard remains unchanged.
Select Done to leave edit mode and display the clone.
In the upper-right corner of the dashboard, select > Upgrade.
Inspect the upgraded dashboard.
To compare two dashboards side by side
1. In the Dynatrace menu, go to Dashboards.
2. Right-click the first dashboard's name in the Dashboards table and open the link in a new window.
3. Right-click the second dashboard's name in the Dashboards table and open the link in a new window.
4. Arrange the browser windows side by side and then visually compare the dashboards.
After you are satisfied with the upgraded dashboard, you can delete the original.

Alternative procedure from the dashboard menu

You can run this procedure with or without creating a backup (see step 3).

In the Dynatrace menu, go to Dashboards.
Select the dashboard name to display the dashboard.
recommended If you haven't already made a backup, you can do so now: in the upper-right corner of the dashboard, select > Clone to create and display a copy of the dashboard. When you clone the dashboard, the clone is displayed and the original dashboard remains unchanged.
In the upper-right corner of the dashboard, select > Upgrade.
- If you cloned the dashboard in the previous step, you are upgrading the clone in this step.
- If you did not clone the dashboard in the previous step, you are upgrading the original dashboard in this step without making a backup.

When a dashboard upgrade is complete:

The following message is displayed at the bottom of the dashboard: The dashboard was successfully upgraded
The tiles on that dashboard no longer display a warning icon because they have all been upgraded to Data explorer tiles
The Upgrade option is no longer available in that dashboard's menu because it has already been upgraded

Check for more dashboards to upgrade

Dynatrace version 1.252+

To check for more dashboards to upgrade, filter the Dashboards page by Custom charts: Yes.

Dashboards you have already upgraded should not be displayed
Any dashboards that still have the Custom charts label still need to be upgraded.

For details on identifying dashboards and charts that still need to be upgraded, see the Does this apply to me? section above.

Upgrade via API

Dynatrace version 1.251+

Using the Dynatrace API, you can upgrade one dashboard at a time or all dashboards at once. In any case, the API will always conveniently skip dashboards that don't have any Custom charts on them, which removes the need to first filter out dashboards without Custom charts.

Upgrade one dashboard

Go to the dashboards API.

Use the migrate endpoint.

plaintext
https://{your-environment-id}/rest-api-doc/index.jsp?urls.primaryName=Configuration%20API#/Dashboards/migrateDashboard

Provide the dashboard ID

Note: Make sure to replace {your-environment-id} with your actual environment ID.

Upgrade all dashboards

Go to the dashboards API.

Use the GET endpoint to retrieve all dashboard IDs.

plaintext
https://{your-environment-id}/rest-api-doc/index.jsp?urls.primaryName=Configuration%20API#/Dashboards/getDashboardStubsList

Loop over all IDs as described in Upgrade one dashboard above.

Note: Make sure to replace {your-environment-id} with your actual environment ID.

Node.js example script

To get you started quickly, feel free to adapt and use the following example Node.js script. We used it to bulk update all dashboards of our own development environment.

Before using the script, make sure you update both lines marked with // TODO with your own information:

Replace {your-environment-id} with your actual environment ID.
Replace {your-api-token} with a valid API token with the proper scope.

js
import fs from "fs";
import fetch from "node-fetch";

async function migrateAllDashboards() {
  // create a backup directory
  if (!fs.existsSync("./BACKUPS")) {
    fs.mkdirSync("./BACKUPS");
  }

  export const ENV_URL = "{your-environment-id}"; // TODO replace this
  export const AUTH_HEADERS = {
      Authorization: `Api-token {your-api-token}`, // TODO replace this
   };
  const dirName = `./BACKUPS/${new URL(ENV_URL).hostname.replace(
    ".",
    "_"
  )}-${Date.now()}`;
  fs.mkdirSync(dirName);

  console.log("Fetching all the dashboards");
  const fetchAllUrl = `${ENV_URL}/api/config/v1/dashboards`;
  const response = await fetch(fetchAllUrl, { headers: AUTH_HEADERS });
  const dashboardsMetadata = await response.json();
  fs.writeFileSync(
    `${dirName}/_ALL_DASHBOARDS_METADATA.json`,
    JSON.stringify(dashboardsMetadata)
  );
  const allDashboards = dashboardsMetadata.dashboards;
  console.log(`Saved the metadata of ${allDashboards.length} dashboards`);

  for (let index = 0; index < allDashboards.length; index++) {
    const db = allDashboards[index];
    const dbId = db.id;
    const fetchDB = `${ENV_URL}/api/config/v1/dashboards/${dbId}`;
    const response = await fetch(fetchDB, { headers: AUTH_HEADERS });
    const dbContent = await response.json();
    // save dashboard content to backup directory
    fs.writeFileSync(`${dirName}/${dbId}.json`, JSON.stringify(dbContent));

    try {
      // attempt migration
      const migrateResponse = await fetch(
        `${ENV_URL}/api/config/v1/dashboards/${dbId}/migrate`,
        {
          method: "PUT",
          headers: {
            "Content-Type": "application/json",
            ...AUTH_HEADERS,
          },
          body: dbId,
        }
      );

      if (migrateResponse.status === 200) {
        if (migrateResponse.errors) {
          console.log(`X ${dbId} updated failed!);
          console.error(migrateResponse.errors);
        }
      } else {
        console.error(`X ${dbId} update failed!`);
        console.error(migrateResponse);
      }
    } catch (error) {
      console.error(`X ${dbId} update failed!`);
      console.error(updateResponse);
    }
  }
}

console.log("### Backup and Migrate\n");
await migrateAllDashboards();
console.log(`### Migration completed\n\n`);

Check for more dashboards to upgrade

Dynatrace version 1.252+

To check for more dashboards to upgrade, filter the Dashboards page by Custom charts: Yes.

Dashboards you have already upgraded should not be displayed
Any dashboards that still have the Custom charts label still need to be upgraded.

For details on identifying dashboards and charts that still need to be upgraded, see the Does this apply to me? section above.

What should I do if an upgrade fails?

Depending on the complexity of the tiles involved, a dashboard upgrade could fail partially (some tiles on the dashboard upgrade successfully and others don't) or completely (no tiles on the dashboard upgrade successfully).

In any case, don't worry about losing data.

Dashboards and tiles are visualizations of your data, not the data itself. Your data is never at risk during an upgrade.
We are tracking upgrade failures and working to improve the upgrade algorithm. See below for details.

Until Dynatrace version 1.265

We are already actively tracking failing upgrades and proactively improving the upgrade algorithm based on it. If your upgrade fails, we automatically log the cause on our servers. All you have to do is contact Dynatrace ONE. They will further assist you with resolving the upgrade issues.

After Dynatrace version 1.265

With Dynatrace version 1.266, we will:

Try to auto-upgrade all of your remaining Custom chart tiles to Data explorer tiles. If any tiles can't be upgraded automatically, we will automatically track these events and proactively reach out to you to resolve them.
Remove the Custom charts page from Dynatrace, which means you will no longer be able to create new Custom charts.

From Dynatrace version 1.266 to version 1.267, use the time to make final cross-checks in case you still find dashboards with Custom charts on them. If you don't hear back from us during version 1.266 and you need your tile to be upgraded 1:1, please reach out to us immediately.

With Dynatrace version 1.268, we will:

Upgrade all remaining tiles as well as we can
Remove all the remaining code for Custom charts
Officially sunset Custom charts.

Where can I get more information?

There's an ongoing Dynatrace Community thread you are welcome to participate in.
To contact Dynatrace ONE, simply sign in to your account, select the chat button in the upper-right corner, and start a new conversation.