diff --git a/src/data/nav.yml b/src/data/nav.yml index 192f9a514..80bfea041 100644 --- a/src/data/nav.yml +++ b/src/data/nav.yml @@ -190,6 +190,8 @@ url: '/explore-docs/custom-viz/configuration-options' - title: Your first custom visualization url: '/explore-docs/custom-viz/build-visualization' + - title: Add your visualization to a dashboard with NerdGraph + url: '/explore-docs/custom-viz/add-to-dashboard-nerdgraph' - title: New Relic One SDK Component library url: '/explore-docs/intro-to-sdk' pages: diff --git a/src/images/custom-viz/my-awesome-dashboard.png b/src/images/custom-viz/my-awesome-dashboard.png new file mode 100644 index 000000000..53db54999 Binary files /dev/null and b/src/images/custom-viz/my-awesome-dashboard.png differ diff --git a/src/images/custom-viz/nav-to-dashboards.png b/src/images/custom-viz/nav-to-dashboards.png new file mode 100644 index 000000000..78cab9eb3 Binary files /dev/null and b/src/images/custom-viz/nav-to-dashboards.png differ diff --git a/src/images/custom-viz/nerdgraph-api-key.png b/src/images/custom-viz/nerdgraph-api-key.png new file mode 100644 index 000000000..427a36d54 Binary files /dev/null and b/src/images/custom-viz/nerdgraph-api-key.png differ diff --git a/src/images/custom-viz/nerdgraph-create-dashboard-with-viz.png b/src/images/custom-viz/nerdgraph-create-dashboard-with-viz.png new file mode 100644 index 000000000..37611bbd4 Binary files /dev/null and b/src/images/custom-viz/nerdgraph-create-dashboard-with-viz.png differ diff --git a/src/images/custom-viz/nerdgraph-successful-dashboard-creation.png b/src/images/custom-viz/nerdgraph-successful-dashboard-creation.png new file mode 100644 index 000000000..4013efb0a Binary files /dev/null and b/src/images/custom-viz/nerdgraph-successful-dashboard-creation.png differ diff --git a/src/images/custom-viz/select-dashboard.png b/src/images/custom-viz/select-dashboard.png new file mode 100644 index 000000000..0300dda56 Binary files /dev/null and b/src/images/custom-viz/select-dashboard.png differ diff --git a/src/markdown-pages/custom-viz/viz-to-dashboard-nerdgraph.mdx b/src/markdown-pages/custom-viz/viz-to-dashboard-nerdgraph.mdx new file mode 100644 index 000000000..df24cc8b8 --- /dev/null +++ b/src/markdown-pages/custom-viz/viz-to-dashboard-nerdgraph.mdx @@ -0,0 +1,835 @@ +--- +path: '/explore-docs/custom-viz/add-to-dashboard-nerdgraph' +title: 'Add your custom visualization to a dashboard with NerdGraph' +template: 'GuideTemplate' +description: 'Add your custom visualization to a dashboard with NerdGraph' +--- + + + +Add your custom visualization to a new or existing dashboard, programmatically, with New Relic's GraphQL API, [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/). + + + +## Before you begin + +If you haven't already: + +- Sign up for a [New Relic account](https://newrelic.com/signup?utm_source=developer-site) +- Install [Node.js](https://nodejs.org/en/download/) +- Complete the first four steps in the [`nr1` quick start](https://one.newrelic.com/launcher/developer-center.launcher?pane=eyJuZXJkbGV0SWQiOiJkZXZlbG9wZXItY2VudGVyLmRldmVsb3Blci1jZW50ZXIifQ==) to install and configure the CLI + +## Create and publish your Nerdpack + +Create a Nerdpack with a visualization. You'll add this visualization to a dashboard using NerdGraph. + + + +Because this guide about using visualizations, not creating and publishing them, it breezes over these topics. If you're unfamiliar with visualizations or would like a thorough explanation of dealing with visualization Nerdpacks, check out the following resources: + +- [Introduction to custom visualizations](/explore-docs/custom-viz) +- [Build your first custom visualization](/explore-docs/custom-viz/build-visualization) + + + +If you already have a visualization you'd like to add to a dashboard, you can skip this section. But don't forget to make the necessary code adjustments to reference your visualization instead of the one this guide uses, called `my-awesome-visualization`. + + + + + +Update your `nr1` CLI: + +```sh +nr1 update +``` + +Now, you have the latest version. + + + + + +Create a visualization, called `my-awesome-visualization`, in a Nerdpack, called `my-awesome-nerdpack`: + +```sh +nr1 create -t visualization -n my-awesome-visualization +[output] {success}✔ {plain}You’re trying to create a visualization outside of a Nerdpack. We’ll create a Nerdpack for you—what do you want to name it? … my-awesome-nerdpack +[output] +[output] {success}✔ {plain}nerdpack created successfully! +[output] {purple}nerdpack {blue}my-awesome-nerdpack {plain}is available at "./my-awesome-nerdpack" +[output] +[output] {success}✔ {plain}visualization created successfully! +[output] {purple}visualization {blue}my-awesome-visualization {plain}is available at "./my-awesome-nerdpack/visualizations/my-awesome-visualization" +``` + +When you build a visualization with `nr1 create`, you get a default visualization. You'll use this default visualization throughout this course. + + + + + +Navigate to your new Nerdpack: + +```sh +cd my-awesome-nerdpack +``` + +From here, you can run `nr1 nerdpack` commands. + + + + + +Publish and subscribe to your Nerdpack: + +```sh +nr1 nerdpack:publish +nr1 nerdpack:subscribe +``` + +Now, that your account is subscribed to your visualization, you can describe your app configurations with JSON and add it to a dashboard with NerdGraph. + + + + + +## Describe your visualization options with JSON + +Whether you're adding your visualization to a new dashboard or an existing one, you need to send your configuration to NerdGraph as JSON. + +Your custom visualization JSON object represents a dashboard widget and consists of the following fields: + +| Field | Type | Description | +|---|---|---| +| `title` | String | Title for your dashboard widget | +| `visualization` | JSON | The metadata for your visualization | +| `visualization.id` | String | Your visualization's ID | +| `rawConfiguration` | JSON | A full configuration of your widget | + + + +You can also add other types of widgets to dashboards with the steps in this guide, but the fields described here are specific to custom visualization widgets. For other widget types, you need to supply different data. + +Explore the API on your own with our [NerdGraph explorer](https://api.newrelic.com/graphiql)! + + + + + + + +Start with a JSON template based on the fields you need to describe your custom visualization: + +```json +{ + title: "", + visualization: { + id: "" + }, + rawConfiguration: {} +} +``` + + + + + +Give your visualization widget a name: + +```json lineHighlight=2 +{ + title: "My Awesome Visualization", + visualization: { + id: "" + }, + rawConfiguration: {} +} +``` + + + + + +Look up your Nerdpack ID from _my-awesome-nerdpack/nr1.json_: + +```json fileName=my-awesome-nerdpack/nr1.json lineHighlight=3 +{ + "schemaType": "NERDPACK", + "id": "ab123c45-678d-9012-efg3-45hi6jkl7890", + "displayName": "MyAwesomeNerdpack", + "description": "Nerdpack my-awesome-nerdpack" +} +``` + +Then, look up your visualization ID from _my-awesome-nerdpack/visualizations/my-awesome-visualization/nr1.json_: + +```json fileName=my-awesome-nerdpack/visualizations/my-awesome-visualization/nr1.json lineHighlight=3 +{ + "schemaType": "VISUALIZATION", + "id": "my-awesome-visualization", + "displayName": "MyAwesomeVisualization", + "description": "", + "configuration": [ + { + "name": "nrqlQueries", + "title": "NRQL Queries", + "type": "collection", + "items": [ + { + "name": "accountId", + "title": "Account ID", + "description": "Account ID to be associated with the query", + "type": "account-id" + }, + { + "name": "query", + "title": "Query", + "description": "NRQL query for visualization", + "type": "nrql" + } + ] + }, + { + "name": "fill", + "title": "Fill color", + "description": "A fill color to override the default fill color", + "type": "string" + }, + { + "name": "stroke", + "title": "Stroke color", + "description": "A stroke color to override the default stroke color", + "type": "string" + } + ] +} +``` + +Set your visualization widget's `visualization.id` to the form `{NERDPACK-ID}.{VISUALIZATION-ID}`: + +```json lineHighlight=4 +{ + title: "My Awesome Visualization", + visualization: { + id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization" + }, + rawConfiguration: {} +} +``` + + + + + +In _my-awesome-nerdpack/visualizations/my-awesome-visualization/nr1.json_, review your configuration options: + +```json fileName=my-awesome-nerdpack/visualizations/my-awesome-visualization/nr1.json lineHighlight=6-38 +{ + "schemaType": "VISUALIZATION", + "id": "my-awesome-visualization", + "displayName": "MyAwesomeVisualization", + "description": "", + "configuration": [ + { + "name": "nrqlQueries", + "title": "NRQL Queries", + "type": "collection", + "items": [ + { + "name": "accountId", + "title": "Account ID", + "description": "Account ID to be associated with the query", + "type": "account-id" + }, + { + "name": "query", + "title": "Query", + "description": "NRQL query for visualization", + "type": "nrql" + } + ] + }, + { + "name": "fill", + "title": "Fill color", + "description": "A fill color to override the default fill color", + "type": "string" + }, + { + "name": "stroke", + "title": "Stroke color", + "description": "A stroke color to override the default stroke color", + "type": "string" + } + ] +} +``` + +The `name` fields in `configuration` are important for describing your visualization widget. + + + + + +Using the `name` field for every configuration object in your visualization's _nr1.json_, build a `rawConfiguration` object for your widget: + +```json lineHighlight=6-15 +{ + title: "My Awesome Visualization", + visualization: { + id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization" + }, + rawConfiguration: { + nrqlQueries: [ + { + accountId: 1234567, + query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago" + } + ], + fill: "pink", + stroke: "green" + } +} +``` + +Here, you've created a `rawConfiguration` object by supplying values for each configuration option in _nr1.json_. Note that `nrqlQueries` is an array because its type is `collection`. The other values are strings. Learn more about these configuration options in [Configure your custom visualization](/explore-docs/custom-viz/configuration-options/). + +Now that you've described your visualization widget in JSON, you can add your configured visualization to a dashboard. In the next section, you'll learn how to create a new dashboard with your visualization. If you already have one ready, skip ahead to [add your visualization to your existing dashboard](#add-your-visualization-to-an-existing-dashboard). + + + + + +## Create a new dashboard with your visualization + +If you want to create a new dashboard for your visualization widget, use NerdGraph's `dashboardCreate()` mutation. + +The NerdGraph `dashboardCreate()` mutation takes the following fields: + +| Field | Type | Description | +|---|---|---| +| `accountId` | Integer | The ID for the account for which you want to create your dashboard | +| `dashboard` | JSON | The details of the dashboard you're creating | +| `dashboard.name` | String | The name of your dashboard | +| `dashboard.permissions` | Enum: PRIVATE, PUBLIC_READ_ONLY, PUBLIC_READ_WRITE | The access control of your dashboard | +| `dashboard.pages` | Array: JSON | The details of your dashboard's pages | +| `dashboard.pages[].name` | String | The name of the dashboard page | +| `dashboard.pages[].widgets` | Array: JSON | The widgets to add to the dashboard page | + + + +You can also pass more fields to `dashboardCreate()` to add details, widgets, and more. Explore the API on your own with our [NerdGraph explorer](https://api.newrelic.com/graphiql)! + + + +For the purposes of this guide, you'll create a dashboard with a single page that contains a single widget—the visualization widget you created in the [last section](#describe-your-visualization-options-with-json). + + + + + +Build out a GraphQL mutation template based on the fields you need to describe your dashboard in `dashboardCreate()`: + +```json +mutation { + dashboardCreate( + accountId: 0, + dashboard: { + name: "", + pages: [ + { + name: "", + widgets: [] + }, + ], + permissions: PRIVATE + } + ) +} +``` + +Here, you've defined the template for a private dashboard. Now, it's time to fill in the details. + + + + + +Look up your account ID and enter it for your `accountId`: + +```json lineHighlight=3 +mutation { + dashboardCreate( + accountId: 1234567, + dashboard: { + name: "", + pages: [ + { + name: "", + widgets: [] + }, + ], + permissions: PRIVATE + } + ) +} +``` + + + + + +Select a name for your dashboard and its page: + +```json lineHighlight=5,8 +mutation { + dashboardCreate( + accountId: 1234567, + dashboard: { + name: "My Awesome Dashboard", + pages: [ + { + name: "One Page to Rule Them All", + widgets: [] + }, + ], + permissions: PRIVATE + } + ) +} +``` + + + + + +In `widgets`, place the widget object you created in the last section: + +```txt lineHighlight=9-26 +mutation { + dashboardCreate( + accountId: 1234567, + dashboard: { + name: "My Awesome Dashboard", + pages: [ + { + name: "One Page to Rule Them All", + widgets: [ + { + title: "My Awesome Visualization", + visualization: { + id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization" + }, + rawConfiguration: { + nrqlQueries: [ + { + accountId: 1234567, + query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago" + } + ], + fill: "pink", + stroke: "green" + } + } + ] + }, + ], + permissions: PRIVATE + } + ) +} +``` + + + + + +Finally, add the return fields to your mutation: + +```txt lineHighlight=31-35 +mutation { + dashboardCreate( + accountId: 1234567, + dashboard: { + name: "My Awesome Dashboard", + pages: [ + { + name: "One Page to Rule Them All", + widgets: [ + { + title: "My Awesome Visualization", + visualization: { + id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization" + }, + rawConfiguration: { + nrqlQueries: [ + { + accountId: 1234567, + query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago" + } + ], + fill: "pink", + stroke: "green" + } + } + ] + }, + ], + permissions: PRIVATE + } + ) { + entityResult { + guid + } + } +} +``` + +Now, you have a mutation ready to send to NerdGraph to create single-page dashboard with a widget for your custom visualization. As a result, you'll see the new dashboard's entity GUID. + +In the next section, you'll learn how to add your visualization to an existing dashboard. If that's not relevant to your goals, skip ahead to [send your request to NerdGraph](#send-your-request-to-nerdgraph). + + + + + +## Add your visualization to an existing dashboard + +If you want to add your visualization widget to an existing dashboard, use NerdGraph's `dashboardAddWidgetsToPage()` mutation. + +The NerdGraph `dashboardAddWidgetsToPage()` mutation takes the following fields: + +| Field | Type | Description | +|---|---|---| +| `guid` | String | The entity GUID for the dashboard to which you're adding your widgets | +| `widgets` | Array: JSON | The widgets to add to the dashboard page | + + + +You can also pass more fields to `dashboardAddWidgetsToPage()` to add details, widgets, and more. Explore the API on your own with our [NerdGraph explorer](https://api.newrelic.com/graphiql)! + + + + + + + +Build out a GraphQL mutation template based on the fields you need to describe your dashboard in `dashboardAddWidgetsToPage()`: + +```txt +mutation { + dashboardAddWidgetsToPage( + guid: "" + widgets: [] + ) { + errors { + description + } + } +} +``` + + + + + +Look up your dashboard's GUID and enter it for `guid`: + +```txt lineHighlight=3 +mutation { + dashboardAddWidgetsToPage( + guid: "AbCdEFghIJkLMNo1PQRSTUVWXYZAbCD2Ef34GHI" + widgets: [] + ) { + errors { + description + } + } +} +``` + + + + + +In widgets, place the widget object you created in [a previous section](#describe-your-visualization-options-with-json): + +```txt +mutation { + dashboardAddWidgetsToPage( + guid: "AbCdEFghIJkLMNo1PQRSTUVWXYZAbCD2Ef34GHI" + widgets: [ + { + visualization: { + id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization" + }, + rawConfiguration: { + nrqlQueries: [ + { + accountId: 1234567, + query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago" + } + ], + fill: "pink", + stroke: "green" + } + }, + ] + ) +} +``` + + + + + +Finally, add the return fields to your mutation: + +```txt +mutation { + dashboardAddWidgetsToPage( + guid: "AbCdEFghIJkLMNo1PQRSTUVWXYZAbCD2Ef34GHI" + widgets: [ + { + visualization: { + id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization" + }, + rawConfiguration: { + nrqlQueries: [ + { + accountId: 1234567, + query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago" + } + ], + fill: "pink", + stroke: "green" + } + }, + ] + ) { + errors { + description + } + } +} +``` + +Now, you have a mutation ready to send to NerdGraph to add your custom visualization to an existing dashboard. As a result, you'll see descriptions of any thrown errors to help you debug issues. + +The last thing you need to do is actually send your request to NerdGraph. + + + + + +## Send your request to NerdGraph + +Send an HTTP request to NerdGraph with the payload you built in previous sections for the mutation that best suits your needs. There are many tools you can use to send an HTTP request, but in this guide, you'll learn how to communicate with NerdGraph using three specific tools: + +- [NerdGraph API explorer](https://api.newrelic.com/graphiql) +- [cURL](https://curl.se/) +- [New Relic CLI](https://developer.newrelic.com/explore-docs/newrelic-cli/) + +If you use another, you can adapt these methods for your favorite development tool. + +### NerdGraph API explorer + +The [NerdGraph API explorer](https://api.newrelic.com/graphiql) is an implementation of [GraphiQL](https://github.com/graphql/graphiql) that lets you explore the NerdGraph APIs. + + + + + +Go to the [NerdGraph API explorer](https://api.newrelic.com/graphiql). + + + + + +Select or create a new API key: + +![Select API key](../../images/custom-viz/nerdgraph-api-key.png) + + + + + +In the center console, paste your mutation: + +![Paste your mutation](../../images/custom-viz/nerdgraph-create-dashboard-with-viz.png) + + + +Make sure you replace the IDs in your mutation with ones that match your account, Nerdpack, and visualization. + + + + + + + +Press **Execute Query** and see the results in the right pane: + +![Execute your query](../../images/custom-viz/nerdgraph-successful-dashboard-creation.png) + +If you created a new dashboard, your response has an entity GUID. This means you've successfully created your dashboard! If you don't have an entity GUID, the response contains error messages to help you debug your query. + +If you added your visualization to an existing dashboard, you should see no errors in the response. If you do see error messages, use them to debug your query. + + + +The NerdGraph API explorer lets you see other fields and change your query without typing everything manually. Use the left pane to explore NerdGraph. + + + + + + + +### cURL + +cURL is a command line utility for making HTTP requests. + + + + + +Select or create a New Relic [user key](https://docs.newrelic.com/docs/apis/get-started/intro-apis/new-relic-api-keys/#user-api-key). Copy this key, because you use it in the next step. + + + + + +Make a request to NerdGraph, using `cURL`: + +```sh +curl https://api.newrelic.com/graphql \ + -H 'Content-Type: application/json' \ + -H 'API-Key: ' \ + --data-binary '{"query": "mutation {dashboardCreate(dashboard: {name: \"My Awesome Dashboard\", pages: [{name: \"One Page to Rule Them All\", widgets: [{title: \"My Awesome Visualization\", visualization: {id: \"ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization\"}, rawConfiguration: {nrqlQueries: [{accountId: 3014918, query: \"FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago\"}], fill: \"pink\", stroke: \"green\"}}]}], permissions: PRIVATE}, accountId: ) { entityResult { guid }}}", "variables": ""}' +``` + + + +Make sure you replace `` with the user key you copied in the last step and `` with your actual account ID. + + + +Here, you send a request to NerdGraph that has two headers, `Content-Type` and `API-Key`, and a binary message body containing one of the mutation queries you built in previous sections. + +If you prefer to use a UI-based client, like [Postman](https://www.postman.com/), you can adapt this method to a format that your client supports. + + + + + +### New Relic CLI + +The [`newrelic`](https://developer.newrelic.com/explore-docs/newrelic-cli/) is a command line interface for reading and writing New Relic data. + + + + + +If you haven't already, install `newrelic` by following the first **two** steps of our [Get started with the New Relic CLI](https://developer.newrelic.com/automate-workflows/get-started-new-relic-cli/) guide. + +Once you've done that, you will have `newrelic` installed and configured for making NerdGraph requests. + + + + + +Make a NerdGraph request using `newrelic nerdgraph query`: + +```sh +newrelic nerdgraph query 'mutation { + dashboardCreate( + accountId: 1234567, + dashboard: { + name: "My Awesome Dashboard", + pages: [ + { + name: "One Page to Rule Them All", + widgets: [ + { + title: "My Awesome Visualization", + visualization: { + id: "de0b4768-1504-4818-a898-da7cd14f0bfb.my-awesome-visualization" + }, + rawConfiguration: { + nrqlQueries: [ + { + accountId: , + query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago" + } + ], + fill: "pink", + stroke: "green" + } + } + ] + }, + ], + permissions: PRIVATE + } + ) { + entityResult { + guid + } + } +}' +``` + + + +Make sure you replace `` with your actual account ID. + + + + + + + +## View your new dashboard + +Now that you've built a dashboard with NerdGraph, it's time to check your work! + + + + + +Go to [New Relic](https://one.newrelic.com). + + + + + +Navigate to **Dashboards**: + +![Navigate to Dashboards](../../images/custom-viz/nav-to-dashboards.png) + + + + + +Select your new dashboard: + +![Select your dashboard](../../images/custom-viz/select-dashboard.png) + + + + + +View your dashboard: + +![My Awesome Dashboard](../../images/custom-viz/my-awesome-dashboard.png) + +The dashboard you created has the `name` you passed in your mutation, "My Awesome Dashboard". It also has the configuration you sent in `rawConfiguration` from the NRQL data query to the fill and stroke colors. + + + + + +## Summary + +Congratulations! In this guide, you used NerdGraph, New Relic's GraphQL API, to add your custom visualization to a dashboard. \ No newline at end of file