Nerdgraph tutorial: Create and manage dashboards

You can use our NerdGraph API to create and manage .

Overview

For an introduction to our custom dashboards feature, see the dashboards docs.

When using NerdGraph to configure dashboards, it helps to understand that our dashboards are considered entities, which have their own entity IDs, similar to other things we consider entities, like monitored apps, hosts, and services.

For how to add and configure widgets and charts in a dashboard, see Configure charts and other widgets.

Operations

We have defined a granular GraphQL API that lets you execute different dashboard operations depending on their goal and scope.

Dashboard CRUD operations

Here are operations related to creating, reading, updating, and deleting (CRUD).

Operation	GraphQL operation type	Notes
`actor > entity()`	query	Get dashboard operation. You can get all dashboard and widget data for a given dashboard entity GUID.
`dashboardCreate()`	mutation	Create dashboard operation. You can create a dashboard attached to a specific account by specifying all its elements, from metadata to widget configuration.
`dashboardUpdate()`	mutation	Update dashboard operation. You can update an existing dashboard using the dashboard entity GUID. To do this, you need to include all the elements in that dashboard, even if you're not updating every element. For example, to update only one of several widgets in a dashboard, you'll need to include all the other widgets and dashboard metadata in your mutation.
`dashboardDelete()`	mutation	Delete dashboard operation. You can delete an existing dashboard given a dashboard entity GUID. This operation executes a logical delete that lets you recover your dashboard.
`dashboardUndelete()`	mutation	Undelete dashboard operation. You can recover a previously deleted dashboard given a dashboard entity GUID. Custom tags cannot be recovered.

Dashboard page operations

Operation	GraphQL operation type	Notes
`dashboardUpdatePage()`	mutation	Update dashboard page operation. You can update one page of an existing dashboard given a dashboard page entity GUID. You need to specify the complete, updated dashboard page elements, from metadata to widget configuration.
`dashboardUpdateWidgetsInPage()`	mutation	Update widgets operation. You can update a set of existing widgets of a dashboard page given a dashboard page entity GUID. You need to specify the set of widgets to be updated and their complete configuration.
`dashboardAddWidgetsToPage()`	mutation	Add widgets operation. You can add a set of new widgets to a dashboard page given a dashboard page entity GUID. You need to specify the set of new widgets and their complete configuration.

Other operations

Operation	GraphQL operation type	Notes
`dashboardCreateSnapshotUrl()`	mutation	Create dashboard page snapshot operation. You can create a public URL for a given dashboard page entity GUID. The dashboard page can then be accessed in the form of a static snapshot in the resulting public URL. The resulting URL will be deprecated three months after creation.
`actor > dashboard > liveUrls()`	query	List all live URLs operation. You can get the complete list of live URLs you have access to. A live URL is a mechanism that allows you to share dashboard pages and widgets publicly with up-to-date or live data.
`dashboardWidgetRevokeLiveUrl()`	mutation	Revoke widget live URL operation. You can revoke a previously created live URL of a widget. As a result, the live URL will become unavailable to the public.

Cross-account dashboards

With NerdGraph, you can create queries of data from more than one New Relic account. You can also create a dashboard using data from across multiple accounts by adding account IDs to the accountIds array.

Here's an example of creating a cross-account dashboard:

mutation {
  dashboardCreate(
    accountId: 1
    dashboard: {
      name: "Cross account queries - NerdGraph API - Cross Account Test1"
      description: null
      permissions: PUBLIC_READ_WRITE
      pages: [
        {
          name: "Page 1"
          description: null
          widgets: [
            {
              visualization: { id: "viz.billboard" }
              layout: { column: 1, row: 1, height: 3, width: 4 }
              title: "Cross Account Total Transaction Count"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
            {
              visualization: { id: "viz.pie" }
              layout: { column: 5, row: 1, height: 3, width: 4 }
              title: "Cross Account Pie"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction FACET accountId()"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
            {
              visualization: { id: "viz.line" }
              layout: { column: 9, row: 1, height: 3, width: 4 }
              title: "Cross Account Line"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction FACET accountId() TIMESERIES"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
          ]
        }
      ]
    }
  ) {
    errors {
      description
      type
    }
  }
}

Limits

We have limited the values you can set to some of the dashboard properties. This allows us to keep dashboards in good shape while boosting their usability.

Dashboard limits

Limit	Value
Maximum number of pages in a dashboard	25
Maximum length of a dashboard name	255
Maximum length of a dashboard description	1024

Dashboard page limits

Limit	Value
Maximum number of widgets in a dashboard page	150
Maximum length of a dashboard page name	255
Maximum length of a dashboard page description	1024

Limit	Value
Maximum length of a widget title	255
Maximum number of entities linked to a widget	1
Maximum number of queries in a widget	20
Maximum layout column of a widget	12
Minimum layout column of a widget	1
Minimum layout row of a widget	1
Maximum layout width of a widget	12
Minimum layout width of a widget	1
Maximum layout height of a widget	32
Minimum layout height of a widget	1

Errors as first class citizens

All dashboard mutations offer a way to ask for errors when being executed. This means that you can perform your dashboard mutations and check the response in order to detect expected potential issues. Every error has a type and a description to help you identify what’s the source of the problem.

Keep in mind that these are expected errors that we are aware of in advance. You should also check for unexpected errors that will be returned in the standard GraphQL errors field.

Nerdgraph tutorial: Create and manage dashboards

Overview

Operations

Dashboard CRUD operations

Dashboard page operations

Other operations

Cross-account dashboards

Dashboard with cross-account query

Limits

Dashboard limits

Dashboard page limits

Widget limits

Errors as first class citizens

Errors as part of every mutation response

Nerdgraph tutorial: Create and manage dashboards

Overview .css-21sua1{background:none;border:none;width:0;padding:0;}

Operations

Dashboard CRUD operations

Dashboard page operations

Other operations

Cross-account dashboards

Limits

Dashboard limits

Dashboard page limits

Widget limits

Errors as first class citizens

Errors as part of every mutation response

Overview