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, depending the write permissions setting for your organization:

  • If write permissions is off, you can make changes to a group and add, update or delete dashboards in it.

  • If write permissions is on, you need write permission for the group to make changes to it. You also need write permission for the group and the dashboard to make changes to a dashboard in the group.

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.

To learn more about write permissions, see the section Setting Write Permissions 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.

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

You can also override the dashboard name, filters, and dashboard variables for a mirror. The overrides only apply to that mirror, so other mirrors are unaffected. To learn more about mirrored dashboards, see the topic Mirroring dashboards in the product documentation.

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. The operations and required permissions are listed in the section Setting Write Permissions in the product documentation. In summary:

  • To add a mirrored dashboard to your group, you need write permission for your group. This is the default for your user default group and custom groups you create. You don’t need write permission any other dashboards or dashboard groups.

  • To apply overrides to a mirror, you need write permission for your group. Overrides customize the mirror’s name, filters, and dashboard variables. Each mirror has its own overrides.

  • To change a mirror’s charts and chart layouts, you need writer permission for the mirror.

To learn more about write permissions and mirrored dashboards, see the section Setting Write Permissions in the product documentation.

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?parms
    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.

  • Add new dashboards to the dashboard group specified in the {id} path parameter:
    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 dashboards to a group.

  • Make 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}/dashboard
    To learn more, see Adding a dashboard clone to a group.

  • Delete the dashboard group specified in the {id} path parameter:
    DELETE https://api.{REALM}.signalfx.com/v2//dashboardgroup/{id}

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 the write permissions feature is available in your organization, you need to ensure you have the correct permissions for any API operations you want to use. To learn more, see the topic Setting Write Permissions in the product documentation.

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. See Adding dashboards to a group.

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/parms. 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 dashboards to a group

Using the SignalFx API, you add dashboards to dashboard groups according to the type of dashboard you’re adding.

Adding new dashboards to a group

To learn how to add new dashboards to a group, see the topic Adding a new dashboard.

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.

Add dashboard clones one at a time, using repeated calls to the POST /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/, 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.

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.

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/, 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.

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

To learn more about mirrored dashboards, see the topic Mirroring Dashboards in the product documentation.

Considerations for adding dashboards

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.

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.

© Copyright 2019 SignalFx.

Third-party license information