NerdGraph tutorial: Create and configure dashboard widgets

With the New Relic dashboards API you can use NerdGraph to build your dashboards. This document explains the different types of widgets you can add to your dashboards, and how to create and get them using the API.

The widget GraphQL schema for query and mutation outputs looks like this:

type Widget {
  id 
  visualization
  layout
  title
  linkedEntities
  configuration
  rawConfiguration
}

Where:

id: The id of the widget.
visualization: The widget’s visualization type, as a string. For example: viz.line, viz.area. See the examples below.
layout: The widget's position and size in the dashboard. The maximum amount of columns is 12.
title: The title of the widget.
linkedEntities: Dashboard Entities related to the widget. Currently it only supports dashboard entities. It is used by the facet linking feature.
configuration: The typed configuration of the widget. It’s a conveniently typed GraphQL representation of the most common widgets: area, bar, billboard, line, markdown, pie, and table.
rawConfiguration: The untyped configuration of the widget. It’s a free-form way (JSON scalar) of storing widget properties not covered by the typed configuration such as heatmap, histogram, bullet, funnel, etc. In this case configuration is null and rawConfiguration holds all the data required by the widget.

The dashboards API supports typed and untyped widgets:

Typed widgets are area, bar, billboard, line, markdown, pie, and table. They can be built directly using NerdGraph, which provides assistance with the required fields.

As an input:

You only need to provide the configuration.
visualization can be null as long as it can be inferred from the provided configuration.
As an output, the API will provide the configuration you provided plus the raw representation in JSON at rawConfiguration. Therefore, rawConfiguration is always a superset of all widget configurations.

Untyped widgets are all other widgets, such as bullet, histogram, inventory, etc.

For untyped widgets, we know and validate the shape of the JSON provided. For example, a heatmap has a specific configuration we know in advance, so we can validate it.

As an input:

configuration is not considered in this case.
rawConfiguration must be provided. See the examples below.
visualization cannot be null and it should be a fixed string like viz.heatmap or viz.bullet.
As an output, the API answers exactly with what was provided in the input.

Area

Area supports multiple nrql queries.

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    configuration: {
      area: {
        nrqlQueries: {
          accountId: 12345678,
          query: "SELECT count(*) FROM Transaction FACET appName TIMESERIES"
        }
      }
    }
    rawConfiguration: null
  }
}

{
  "visualization": "viz.area",
  "configuration": {
    "area": {
      "nrqlQueries": [
        {
          "accountId": 12345678,
          "query": "SELECT count(*) FROM Transaction FACET appName TIMESERIES"
        }
      ]
    },
    "bar": null,
    "billboard": null,
    "line": null,
    "markdown": null,
    "pie": null,
    "table": null
  },
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT count(*) FROM Transaction FACET appName TIMESERIES"
      }
    ]
  }
}

Bar

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{  
  widgets: {
    configuration: {
      bar: {
        nrqlQueries: {
          accountId: 12345678,
          query: "SELECT count(*) FROM Transaction FACET appName"
        }
      }
    }
    rawConfiguration: null
  }  
}

{
  "visualization": "viz.bar",
  "configuration": {
    "area": null,
    "bar": {
      "nrqlQueries": [
        {
          "accountId": 12345678,
          "query": "SELECT count(*) FROM Transaction FACET appName"
        }
      ]
    },
    "billboard": null,
    "line": null,
    "markdown": null,
    "pie": null,
    "table": null
  },
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT count(*) FROM Transaction FACET appName"
      }
    ]
  }
}

Billboard

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

thresholds

[Object]

Optional. Array of thresholds to categorize the results of the query in different groups:

alertSeverity: It can be NOT_ALERTING, WARNING, and CRITICAL.
value: Threshold value for the alerting group.

{  
  widgets: {
    configuration: {
      billboard: {
        nrqlQueries: {
          accountId: 12345678,
          query: "SELECT count(*) FROM Transaction FACET appName"
        }
        thresholds: {
          alertSeverity: CRITICAL
          value: 3
        }
      }
    }
    rawConfiguration: null
  }
}

{
  "visualization": "viz.billboard",
  "configuration": {
    "area": null,
    "bar": null,
    "billboard": {
      "nrqlQueries": [
        {
          "accountId": 12345678,
          "query": "SELECT count(*) FROM Transaction FACET appName"
        }
      ],
      "thresholds": [
        {
          "alertSeverity": "CRITICAL",
          "value": 3
        }
      ]
    },
    "line": null,
    "markdown": null,
    "pie": null,
    "table": null
  },
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT count(*) FROM Transaction FACET appName"
      }
    ],
    "thresholds": [
      {
        "alertSeverity": "CRITICAL",
        "value": 3
      }
    ]
  }
}

Line

Line supports multiple nrql queries.

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    configuration: {
      line: {
        nrqlQueries: {
          accountId: 12345678,
          query: "SELECT count(*) FROM Transaction FACET appName TIMESERIES"
        }
      }
    }
    rawConfiguration: null
  }
}

{
  "visualization": "viz.line",
  "configuration": {
    "area": null,
    "bar": null,
    "billboard": null,
    "line": {
      "nrqlQueries": [
        {
          "accountId": 12345678,
          "query": "SELECT count(*) FROM Transaction FACET appName TIMESERIES"
        }
      ]
    },
    "markdown": null,
    "pie": null,
    "table": null
  },
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT count(*) FROM Transaction FACET appName TIMESERIES"
      }
    ]
  }
}

Markdown

Widget data element	Description
`text` String	Content to be added in the markdown widget.

Widget data element

Description

text

String

Content to be added in the markdown widget.

{
  "visualization": "viz.markdown",
  "configuration": {
    "area": null,
    "bar": null,
    "billboard": null,
    "line": null,
    "markdown": {
      "text": "My markdown"
    },
    "pie": null,
    "table": null
  },
  "rawConfiguration": {
    "text": "My markdown"
  }
}

Pie

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    configuration: {
      pie: {
        nrqlQueries: {
          accountId: 12345678,
          query: "SELECT count(*) FROM Transaction FACET appName"
        }
      }
    }
    rawConfiguration: null
  }  
}

{
  "visualization": "viz.pie",
  "configuration": {
    "area": null,
    "bar": null,
    "billboard": null,
    "line": null,
    "markdown": null,
    "pie": {
      "nrqlQueries": [
        {
          "accountId": 12345678,
          "query": "SELECT count(*) FROM Transaction FACET appName"
        }
      ]
    },
    "table": null
  },
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT count(*) FROM Transaction FACET appName"
      }
    ]
  }
}

Table

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    configuration: {
      table: {
        nrqlQueries: {
          accountId: 12345678,
          query: "SELECT count(*) FROM Transaction"
        }
      }
    }
    rawConfiguration: null
  }
}

{
  "visualization": "viz.table",
  "configuration": {
    "area": null,
    "bar": null,
    "billboard": null,
    "line": null,
    "markdown": null,
    "pie": null,
    "table": {
      "nrqlQueries": [
        {
          "accountId": 12345678,
          "query": "SELECT count(*) FROM Transaction"
        }
      ]
    }
  },
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT count(*) FROM Transaction"
      }
    ]
  }
}

Area (predefined metrics)

Widget data element	Description
`duration` Long	Duration of the requested time window, in milliseconds. When provided with `endTime`, the time window is set to the last `x` milliseconds ending at the specified time. If `endTime` is null, the time window is set to the last `x` milliseconds ending now.
`endTime` Long	Optional. End of the time window, in milliseconds.
`entityIds` [Integer]	Array of source agent Ids to fetch data from.
`metrics` [Object]	For `type` `SCOPE_BREAKDOWN` only. List of metrics to be fetched.
`type` String	Type of the predefined chart. It can be: `APPLICATION_BREAKDOWN`, `BACKGROUND_BREAKDOWN`, `BROWSER_BREAKDOWN`, `GC_RUNS_BREAKDOWN`, `SCOPE_BREAKDOWN`, `SOLR_BREAKDOWN.`

{
  widgets: {
    visualization: "viz.area"
    configuration: null
    rawConfiguration: {
      type:SCOPE_BREAKDOWN
      endTime: null
      entityIds: [1]
      metrics: [{
        name: "Mobile/Activity/Name/Display"
      }]
      duration: 3600
    }
  }
}

{
  "visualization": "viz.area",
  "configuration": null,
  "rawConfiguration": {
    "type": "SCOPE_BREAKDOWN",
    "endTime": null,
    "entityIds": [1],
    "metrics": [
      {
        "name": "Mobile/Activity/Name/Display"
      }
    ],
    "duration": 3600
  }
}

Bullet

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

limit

Float

Goal against which all query results are compared to.

{
  widgets: {
    visualization: "viz.bullet"
    configuration: null
    rawConfiguration: {
      nrqlQueries: [
        {
          accountId: 12345678,
          query: "SELECT count(*) FROM Transaction"
        }
      ]
      limit: 2.4
    }
  }
}

{
  "visualization": "viz.bullet",
  "configuration": null,
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT count(*) FROM Transaction"
      }
    ],
    "limit": 2.4
  }
}

Event feed

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    visualization: "viz.event-feed"
    configuration: null
    rawConfiguration: {
      nrqlQueries: [      
        {
          accountId: 12345678,
          query: "SELECT * FROM InfrastructureEvent"
        }
      ]    
    }
  }
}

{
  "visualization": "viz.event-feed",
  "configuration": null,
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT * FROM InfrastructureEvent"
      }
    ]
  }
}

Funnel

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    visualization: "viz.funnel"
    configuration: null
    rawConfiguration: {
      nrqlQueries: [      
        {
          accountId: 12345678,
          query: "SELECT funnel(SESSION,
            WHERE name ='Controller/about/main' AS 'Step 1',
            WHERE name ='Controller/about/careers' AS 'Step 2')
            FROM PageView"
        }
      ]
    }
  }
}

{
  "visualization": "viz.funnel",
  "configuration": null,
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT funnel(SESSION, \n WHERE name ='Controller/about/main' AS 'Step 1', \n WHERE name ='Controller/about/careers' AS 'Step 2') \n FROM PageView"
      }
    ]
  }
}

Heatmap

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    visualization: "viz.heatmap"
    configuration: null
    rawConfiguration: {
      nrqlQueries: [      
        {
          accountId: 12345678,
          query: "SELECT histogram(duration) FROM Transaction Facet appName"
        }
      ]
    }
  }
}

{
  "visualization": "viz.heatmap",
  "configuration": null,
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT histogram(duration) FROM Transaction Facet appName"
      }
    ]
  }
}

Histogram

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    visualization: "viz.histogram"
    configuration: null
    rawConfiguration: {
      nrqlQueries: [      
        {
          accountId: 12345678,
          query: "SELECT histogram(duration) FROM Transaction"
        }
      ]
    }
  }
}

{
  "visualization": "viz.histogram",
  "configuration": null,
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT histogram(duration) FROM Transaction"
      }
    ]
  }
}

Inventory

Widget data element

Description

accountId

Integer

Source account to fetch data from.

filters

Object

Map of the filters to be applied to the infrastructure sources.

sources

[String]

List of the infrastructure sources to get data from. For more information see our docs on how inventory entries look like.

{
  widgets: {
    visualization: "infra.inventory"
    configuration: null
    rawConfiguration: {
      accountId: 12345678,  
      filters: {
        providerAccountId: "1"
      }
      sources: [ "aws/elastocache/cluster", "aws/elasticache/node" ]
    }
  }
}

{
  "visualization": "infra.inventory",
  "configuration": null,
  "rawConfiguration": {
    "accountId": 12345678,
    "filters": {
      "providerAccountId": "1"
    },
    "sources": ["aws/elastocache/cluster", "aws/elasticache/node"]
  }
}

JSON

Widget data element

Description

accountId

Integer

Source account to fetch data from.

query

String

The NRQL query that provides the data for the widget.

{
  widgets: {
    visualization: "viz.json"
    configuration: null
    rawConfiguration: {
      nrqlQueries: [      
        {
          accountId: 12345678,
          query: "SELECT * FROM Transaction"
        }
      ]
    }
  }
}

{
  "visualization": "viz.json",
  "configuration": null,
  "rawConfiguration": {
    "nrqlQueries": [
      {
        "accountId": 12345678,
        "query": "SELECT * FROM Transaction"
      }
    ]
  }
}

Line (metrics)

Widget data element	Description
`accountId` Integer	Source account to fetch data from.
`compareWith` Object	Optional. Additional time window to query. For example: `{ offsetDuration: 86400000 presentation: { "#c001", "Yesterday" } }`
`duration` Long	Duration of the requested time window, in milliseconds. When provided with `endTime`, the time window is set to the last `x` milliseconds ending at the specified time. If `endTime` is null, the time window is set to the last `x` milliseconds ending now.
`endTime` Long	End of the time window, in milliseconds.
`entityIds` [Integer]	Array of source agent Ids to fetch data from.
`facet` String	Optional. Facet the data by the given attribute. It can be `host`, `agent`, `application`, or `mobile_version`.
`limit` Integer	Optional. Maximum amount of series to be returned.
`metrics` [Object]	List of metrics to be fetched.
`orderBy` String	Optional. Used to sort the results in descending order.

{
  widgets: {
    visualization: "viz.line"
    configuration: null
    rawConfiguration: {
      accountId: 12345678,      
      duration: 36000
      endTime: null
      entityIds: [ 100 ]
      facet: null
      limit: null
      metrics: [{
        name: "Errors/all"
        values: [ "error_rate" ]
      }]
      orderBy: null
      compareWith: []
      rawMetricName: "Errors/all"
    }
  }
}

{
  "visualization": "viz.line",
  "configuration": null,
  "rawConfiguration": {
    "accountId": 12345678,
    "duration": 36000,
    "endTime": null,
    "entityIds": [100],
    "facet": null,
    "limit": null,
    "metrics": [
      {
        "name": "Errors/all",
        "values": ["error_rate"]
      }
    ],
    "orderBy": null,
    "compareWith": [],
    "rawMetricName": "Errors/all"
  }
}

Service map

Widget data element	Description
`accountId` Integer	Source account to fetch data from.
`additionalEntities` [Object]	Optional. An array of additional entities to include. The target is the entity downstream, while the source is upstream. `Type`, `vendor`, `target`, and `source` are optional.
`deemphasizedConditions` [Object]	Optional. Entities with these conditions have a faded appearance in the map.
`hiddenEntities` [Object]	Optional. Entities to be excluded from the map.
`primaryEntities` [Object]	The primary entities which start the map (most upstream).

{
  widgets: {
    visualization: "topology.service-map"
    configuration: null
    rawConfiguration: {
      accountId: 12345678,       
      entitySearchQuery: "alertStatus IN ('RED')"
      additionalEntities: [{
        guid: "AAA"
        type: "APPLICATION"
        vendor: "Company inc."
        sourceGuid: "BBB"
        targetGuid: "CCC"
      }]
      deemphasizedConditions: {
        alertStatus: [ GREEN ]
        entityType: [ APM_APPLICATION_ENTITY ]
      }
      hiddenEntities: [{
        guid: "XXX_2"
        sourceGuid: "YYY_2"
        targetGuid: "ZZZ_2"
      }]
      primaryEntities: [{
        guid: "AAA"
      }]
    }
  }
}

{
  "visualization": "topology.service-map",
  "configuration": null,
  "rawConfiguration": {
    "accountId": 12345678,
    "entitySearchQuery": "alertStatus IN ('RED')",
    "additionalEntities": [
      {
        "guid": "AAA",
        "type": "APPLICATION",
        "vendor": "Company inc.",
        "sourceGuid": "BBB",
        "targetGuid": "CCC"
      }
    ],
    "deemphasizedConditions": {
      "alertStatus": ["GREEN"],
      "entityType": ["APM_APPLICATION_ENTITY"]
    },
    "hiddenEntities": [
      {
        "guid": "XXX_2",
        "sourceGuid": "YYY_2",
        "targetGuid": "ZZZ_2"
      }
    ],
    "primaryEntities": [
      {
        "guid": "AAA"
      }
    ]
  }
}

NerdGraph tutorial: Create and configure dashboard widgets

Widget schema and types .css-21sua1{background:none;border:none;width:0;padding:0;}

Types of widgets

Untyped widgets

Typed widget definitions

Area

Input

Output

Bar

Input

Output

Billboard

Input

Output

Line

Input

Output

Markdown

Input

Output

Pie

Input

Output

Table

Input

Output

Untyped widget definitions

Area (predefined metrics)

Input

Output

Bullet

Input

Output

Event feed

Input

Output

Funnel

Input

Output

Heatmap

Input

Output

Histogram

Input

Output

Inventory

Input

Output

JSON

Input

Output

Line (metrics)

Input

Output

Service map

Input

Output

Widget schema and types