SignalFx Developers Guide

Working with Dashboard Groups

Dashboard groups bring together related dashboards so that users can find them and view them in a single place. All dashboards belong to at least one group, and groups usually contain multiple dashboards. In the web UI, groups appear as named lists of dashboards.

To view a dashboard group created with the API in the web UI, display one of its dashboards. Get the dashboard ID of the dashboard, then enter the following URL in your browser:

https://app.{REALM}.signalfx.com/#/dashboard/<DASHBOARD_ID>

The web UI displays the dashboard group name at the top of the page. The dashboards belonging to the group appear as linked tabs directly below the dashboard group name:

Dashboard group with three dashboards
Dashboard group with three dashboards

The dashboards also appear in the catalog.

Dashboard group types

SignalFx offers three types of dashboard groups, each with its own features:

Built-in

Added by SignalFx when you add a data-monitoring integration. They contain dashboards and charts that give you immediate visibility into the key metrics provided by the integration.

You can copy dashboards from built-in groups to other group types, but you can’t add dashboards to a built-in group.

Custom

Dashboards that you create. You can add new dashboards to them or copy dashboards to them from other groups including built-in groups. You can add, update, or delete dashboards in these groups.

User

A single dashboard added by SignalFx, but entirely controlled by you. Its name is your email address. Your user dashboard group is a personal workspace in which you can learn and experiment with dashboards and charts.

To learn more about dashboard groups, see the topic Dashboard Basics in the product documentation.

Mirrored dashboards

If the mirrored dashboard feature is available in your organization, you can add a mirror of a dashboard to a dashboard group. Dashboard mirroring lets you add the same dashboard to multiple groups or even multiple times to the same group.

To add a mirror of a dashboard, use the operation PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}

All mirrors of a dashboard contain the same charts and chart layouts. You can edit a dashboard from any of its mirrors, and any changes you make to the dashboard are visible in all mirrors.

The topic Mirroring dashboards in the product documentation describes mirrored dashboards in more detail.

API operations

The Dashboard Groups API lets you perform all of the tasks involved in managing dashboard groups, including:

  • Creating a new dashboard group:
    POST https://api.{REALM}.signalfx.com/v2/dashboardgroup
    To learn more, see Creating dashboard groups.

  • Retrieving the properties of one or more dashboard groups, using search criteria encoded on the URL:
    GET https://api.{REALM}.signalfx.com/v2/dashboardgroup?params
    To learn more, see Retrieving dashboard groups.

  • Retrieving the properties of a single dashboard group specified by its ID:
    GET https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}
    To learn more, see Retrieving dashboard groups.

  • Adding a new dashboard to the dashboard group specified in the {id} path parameter:

    • To add a dashboard and have it contain existing charts, use the operation
      POST https://api.{REALM}.signalfx.com/v2/dashboard

    • To add a dashboard and have it contain new charts, use the operation
      POST https://api.{REALM}.signalfx.com/v2/dashboard/simple

    Then, to add the new dashboard to the group, use the operation
    PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}
    This operation also lets you update the properties of a dashboard group, such as the teams associated with the group. To learn more, see Adding a new dashboard

  • Saving a deep copy or clone of a dashboard to the group specified in the {id} path parameter:
    POST https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}
    To learn more, see Adding a dashboard clone to a group.

  • Deleting the dashboard group specified in the {id} path parameter:
    DELETE https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}
    To learn more, see Deleting a dashboard group.

If the mirrored dashboard feature is available in your organization, you can also use the API to add a mirrored dashboard. To do this, update the list of dashboards associated with the group using the operation
PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}
See Adding a mirrored dashboard to a group.

If you’re using SignalFx Enterprise Edition, you need to ensure you have the correct permissions for any API operations you want to use. These are summarized in the section Write permissions.

Creating dashboard groups

When you create a new dashboard group using the API, SignalFx creates a new dashboard for it. The dashboard ID for this dashboard is returned in the response body.

You can’t add dashboards to a new dashboard group when you create the group, but after you create a group you can add dashboards to it. To learn how to add dashboards, see Adding a new dashboard.

Retrieving dashboard groups

The API has two ways to retrieve dashboard groups:

Search criteria

Retrieves one or more dashboard groups based on their dashboard group name, using the operation GET https://api.{REALM}.signalfx.com/v2/dashboardgroup/params For this operation, use the name query parameter to specify search criteria. A name match occurs if the string matches any part of the name.

For example, the query specification name="per" matches the following (ellipses represent other parts of the name): * "…​dropped per day…​" * "…​95th *per*centile" * "*per*sonal disk usage…​"

+ If you specify name="", the system ignores the search string.

+ This operation returns one or more dashboard group objects.

Dashboard group ID

Retrieves a single dashboard group based on its SignalFx-assigned identifier. You receive this value in the id property of the response body when you create the group.

You can also find the ID in the web UI, by clicking on the group name. In the browser address bar, the group ID appears after the groupId query parameter.

This operation returns a single dashboard group object.

To see the dashboard group object schema, refer to the response body description in the reference documentation for Retrieve Dashboard Group Using ID.

Adding a dashboard clone to a group

A dashboard clone is a full copy of a dashboard that is independent of the dashboard from which it is copied. When you change the clone, the original remains unchanged. If the owner of the original changes it, your copy remains unchanged.

You can clone all dashboards including built-in dashboards and user-specific dashboards. You can also clone dashboards with or without changes. Use this feature to develop and test a dashboard in a "QA" dashboard group and then promote it to production when you’re ready.

Add dashboard clones one at a time, using repeated calls to the POST https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}/dashboard operation:

  1. In the web UI, open the dashboard you want to copy.

  2. In the address bar, look for the URL https://api.{REALM}.signalfx.com/#/dashboard/<DASHBOARD_ID>, where {REALM} is the realm assigned to your org, and <DASHBOARD_ID> is the alphanumeric string that identifies your dashboard. Store the dashboard ID.

  3. In the web UI, click the name of the dashboard group to which you want to add the clone. In the browser address bar, the group ID appears after the groupId query parameter. Store the group ID.

  4. Use the operation POST https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}/dashboard to add the clone:

    1. Change the {id} path parameter to the ID of the dashboard group.

    2. In the request body for the operation, set the sourceDashboard property to the ID of the dashboard you want to clone.

    3. The response body contains the ID of the cloned dashboard.

Deleting a dashboard group

When you delete a dashboard group, the system deletes its dashboards and the charts that belong to those dashboards. Note that this only happens with dashboard groups; when you delete a dashboard using the API, the system turns its charts into orphans rather than deleting them.

Adding a mirrored dashboard to a group

Before you add a mirrored dashboard to a dashboard group, check the following:

  • Ensure that the write permissions feature is available for your organization.

  • Ensure that the mirrored dashboards feature is available for your organization.

  • Ensure that you have write permission for the destination dashboard group.

You don’t need write permission for the original dashboard.

Permissions for mirrored dashboards

What you can do with mirrored dashboards depends on the write permissions you have for the dashboard groups and dashboards related to the mirror. To learn more, see the section Write permissions.

Add the mirrored dashboard

To add a mirrored dashboard to a dashboard group:

  1. In the web UI, open the dashboard you want to copy.

  2. In the address bar, look for the URL https://api.{REALM}.signalfx.com/#/dashboard/<DASHBOARD_ID>, where {REALM} is the realm assigned to your org, and <DASHBOARD_ID> is the alphanumeric string that identifies your dashboard. Store the dashboard ID.

  3. In the web UI, click the name of the dashboard group into which you want to add the clone. In the browser address bar, the group ID appears after the groupId query parameter. Store the group ID.

  4. Use the operation GET https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id} to get the dashboard group object for the new dashboards.
    This is an important step. To add a mirrored dashboard to a group, you have to update the group’s list of dashboards. This update overwrites the existing list. To keep the group’s existing list of dashboards, you need to get the group and append the mirrored dashboard to the list.

  5. Create a dashboard configuration for the mirrored dashboard and append it to the dashboardConfigs array property of the group object you retrieved in the previous step. To see the properties of a dashboard configuration, refer to the request body specifications for the operation Update Single Dashboard Group. The dashboardConfigs property is an array of dashboard configurations.
    You have several options for overriding filters and dashboard variables for a dashboard mirror. Refer to the section Mirrored dashboard overrides to see detailed instructions for each option.

  6. Use the operation PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id} to update the group with the new dashboards.

Mirrored dashboard overrides

By default, a mirrored dashboard has the same display name, description, filters, and dashboard variables of the dashboard being mirrored.

To differentiate the mirror, you have the following options:

  • Name override: Gives the mirror a different name, allowing you to identify it in the dashboard group.

  • Description override: Lets you give a detailed explanation of the mirror and its differences from the dashboard being mirrored.

  • Filter overrides: Gives you options for overriding the filters that SignalFx applies to the charts displayed in the mirror. See Mirrored dashboard filter overrides.

  • Dashboard variable overrides: Gives you options for overriding the dashboard variables that SignalFx provides to chart viewers. See Mirrored dashboard variable overrides.

Mirrored dashboard overrides only apply to the mirror that contains them, so other mirrors are unaffected.

The following sections provide an overview of mirrored dashboard overrides. The reference documentation for the Update Single Dashboard Group request body describes how to set overrides for each option.

Mirrored dashboard filter overrides

Filter overrides are specified in the dashboardConfigs.filtersOverride.sources array property (see the request body for Create Single Dashboard Group). Overrides apply to all of the filters, and you can’t add new filters.

Use one of these options to override the filters:

Replace all filters

Ignore the filters specified in the dashboard being mirrored and replace them with a list of filters.

Use all of the original filters

Use the filters specified in the dashboard being mirrored.

Clear all of the original filters

Ignore the filters specified in the dashboard being mirrored but don’t replace them with anything. The mirrored dashboard has no filters.

Mirrored dashboard variable overrides

Dashboard variable overrides are specified in the dashboardConfigs.filtersOverride.variables array property (see the request body for Create Single Dashboard Group).

For a dashboard variable, you can only override the value list (called the default value in the web UI). This list is stored in dashboardConfigs.filtersOverride.variables[n].value.

Replace the value list

Replace the contents of dashboardConfigs.filtersOverride.variables[n].value.

Use the original value list

Use the dashboardConfigs.filtersOverride.variables[n].value specified in the dashboard being mirrored.

Clear the original value list

Clear the contents of dashboardConfigs.filtersOverride.variables[n].value.

You can apply different options to the same mirrored dashboard. For example, you can replace all of the filters from the dashboard being mirrored, and at the same time use all of the dashboard variable values from the dashboard being mirrored.

Write permissions

If you’re using SignalFx Enterprise Edition, you need to consider write permissions when you manage dashboards and dashboard groups. The following table summarizes the write permissions rules:

Table 1. Dashboard group write permissions summary
Activity Needs group write permission Needs dashboard write permission API operation

Delete a dashboard

X

DELETE https://api.{REALM}.signalfx.com/v2/dashboard/{id}

Add a new dashboard to a group

X

POST https://api.{REALM}.signalfx.com/v2/dashboard/simple

Clone an existing dashboard into a group

X

POST https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}/dashboard

Add a mirrored dashboard to a group

X

PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}¹

Change the order of group tabs in the web UI

X

PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}²

Rename the group

X

PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}²

Delete the group

X

DELETE https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}

Manage the teams associated with a group

X

PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}²

Change the overrides of a non-mirrored dashboard and save it back to the group

X

PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}¹

Change the overrides of a mirrored dashboard and save it back to the group

X

PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}¹

Make non-override changes to a dashboard or mirror in the group

X

PUT https://api.{REALM}.signalfx.com/v2/dashboard/{id}²

Delete a mirror from the group

X

PUT https://api.{REALM}.signalfx.com/v2/dashboardgroup/{id}¹

Delete a non-mirrored dashboard from the group

X

DELETE https://api.{REALM}.signalfx.com/v2/dashboard/{id}³

Add a chart to a dashboard

X

PUT https://api.{REALM}.signalfx.com/v2/dashboard/{id}

Delete a chart from a dashboard

X

PUT https://api.{REALM}.signalfx.com/v2/dashboard/{id}

Edit and save a chart in a dashboard

X

PUT https://api.{REALM}.signalfx.com/v2/dashboard/{id}

Paste a chart into a dashboard

X

PUT https://api.{REALM}.signalfx.com/v2/dashboard/{id}

Resize and re-arrange charts

X

PUT https://api.{REALM}.signalfx.com/v2/dashboard/{id}

Rename a dashboard

X

PUT https://api.{REALM}.signalfx.com/v2/dashboard/{id}

Delete a dashboard

X

DELETE https://api.{REALM}.signalfx.com/v2/dashboard/{id}

¹ Specifies updates to properties in the dashboardConfigs request body property
² Specifies updates to properties that aren’t in the dashboardConfigs request body property
³ Since the dashboard isn’t mirrored, it only exists in a single group. Deleting it deletes it from the group.
⁴ Adds an element to the charts request body property for a dashboard
⁵ Updates an element in the charts request body property for a dashboard

The section Setting Write Permissions in the product documentation describes the write permissions for dashboard-related tasks in the web UI.

© Copyright 2019 SignalFx.

Third-party license information