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 chart 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+ will offer web UI and API options for upgrading your charts and dashboards
  • Dynatrace version 1.252+ will offer 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 charts and dashboards created using the Data explorer. This applies only to our old Custom chart functionality, which predated the Data explorer.

A tile that needs to be upgraded will display a warning icon and tooltip.

How can I upgrade?

Dynatrace 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.

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 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

1. Display a dashboard that has a tile that needs to be upgraded.

   

2. 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 and new charts side by side.

   

3. Inspect the chart to verify that it converted properly.

4. If you are satisfied with the conversion, choose one of the options:

   • To preserve the old chart for now, select Pin to dashboard, and then select another dashboard or save it as a copy on the same dashboard.
   • To overwrite the old tile with the converted tile, select Save changes to dashboard.

Upgrade entire dashboard

To upgrade an entire dashboard (all tiles on the dashboard at once)

1. In the Dynatrace menu, go to Dashboards.
2. Find the dashboard in the table of dashboards.
3. In that dashboard's row, select More (…) > Upgrade.

Alternative procedure:

1. In the Dynatrace menu, go to Dashboards.
2. Display the dashboard.
3. optional If you haven't already made a backup, you can do so now: in the upper-right corner of the dashboard, select More (…) > Clone to create and display a copy of the dashboard.
4. In the upper-right corner of the dashboard, select More (…) > Upgrade.

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

Upgrade via API

Dynatrace 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

1. Go to the dashboards API.

2. Use the migrate endpoint.

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

3. Provide the dashboard ID

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

Upgrade all dashboards

1. Go to the dashboards API.

2. Use the GET endpoint to retrieve all dashboard IDs.

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

3. 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.

jscopydownload
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`);

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.