Installing the Dashboard Bundle for Amazon Athena

The Amazon Athena variant of the dashboard bundle contains Grafana dashboard definitions that query build data through Amazon Athena, together with the Athena schema statements and the Terraform modules that provision an Amazon Managed Grafana instance.

This page covers importing and upgrading those dashboards. Setting up the Athena schema and the Athena data export itself is covered in the Develocity Reporting via Amazon Athena User Manual.

Contact your technical contact at Gradle for assistance integrating the dashboards into your on-premises or cloud Grafana instance.

Prerequisites

Before importing the dashboards, you need:

 Throughout the following steps, all shell commands are expected to run in the root directory of the extracted bundle.

The dashboard JSON files reference the Grafana Athena data source by a fixed UID. Bundle 1.10.1 and later reference develocity-reporting-athena, while earlier bundles reference athena-datasource-uid-placeholder.

If your Grafana Athena data source already uses the UID that your bundle references, the dashboards work without modification. Otherwise, insert the UID of your Grafana Athena data source into the dashboard JSON files. The following command inserts the UID into all JSON files at once:

find ./dashboards -type f -name '*.json' -exec sed -i.bak 's/develocity-reporting-athena/YOUR-DATASOURCE-UID/g' {} \; \
    && find ./dashboards -type f -name '*.json.bak' -exec rm {} \;
 For bundles earlier than 1.10.1, replace develocity-reporting-athena with athena-datasource-uid-placeholder in the command above.

You can find your data source’s UID in the Grafana UI by navigating to Connections → Data Sources and clicking the Athena data source. The UID is displayed in the URL.

Example of Showing the Data Source’s UID in Grafana
Example of Showing the Data Source’s UID in Grafana

Compatibility

For the Grafana versions the dashboards are tested against, see Grafana dashboard compatibility.

For the Athena schema version each bundle version requires, see Amazon Athena dashboard bundle compatibility.

Most of the Gradle-provided dashboards rely on specific tags and custom values being present on Build Scan records to render the intended visualizations.

Tags used within the dashboards:

  1. CI: classifies builds as either CI builds (the tag is present) or local builds (the tag is absent)

Custom values used within the dashboards:

  1. Git repository: the URI of the Git repository the build ran in, for example [email protected]:gradle/gradle.git

  2. CI provider: the name of the CI provider that ran the build, for example GitHub Actions

If you use the Common Custom User Data Gradle plugin or the Common Custom User Data Maven extension, this information is added to every Build Scan automatically.

Installation Methods

The steps for importing the dashboards differ depending on the type of Grafana installation. Besides manual import and the built-in provisioning mechanism, Grafana also offers a variety of infrastructure as code options for managing dashboards.

Using the Built-in Grafana Provisioning Mechanism

Use if you have access to the file system of the Grafana server.

Grafana has a provisioning mechanism that lets you point it at a directory containing dashboard definitions in JSON format. Grafana watches that directory for changes and automatically imports new dashboards or updates existing ones.

Steps:

  1. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in Prerequisites.

  2. Copy the contents of the dashboards folder from the bundle into a directory on your Grafana server. This guide assumes you copied the contents into /var/lib/grafana/dashboards, so that you end up with the following directory structure:

    /var/lib/grafana/dashboards/
├─ 00 - Overview/
│  ├─ global-volume.json
│  ├─ project-volume.json
├─ 10 - Environment/
│  ├─ build-tools.json
│  ├─ ...
├─ ...

  3. Place a dashboards.yaml file with the following content into Grafana’s provisioning directory at /etc/grafana/provisioning/dashboards/.

    apiVersion: 1
providers:
  - name: 'Gradle Develocity Dashboards'
    type: file
    allowUiUpdates: false
    disableDeletion: true
    updateIntervalSeconds: 60
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

Using Grafana Provisioning With Helm and Kubernetes

Use if you are self-hosting Grafana in a Kubernetes cluster and you manage your Grafana deployment with Helm.

The Grafana Helm chart contains an option that allows Grafana to discover and collect dashboards stored in ConfigMaps within the cluster.

Steps:

  1. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in Prerequisites.

  2. Place the dashboards into ConfigMaps with the label grafana_dashboard: "1". Grafana recommends creating one ConfigMap per dashboard. You can create ConfigMaps individually per dashboard using the following kubectl command:

    kubectl create configmap overview-global-volume-dashboard \
        -n <YOUR-NAMESPACE> \
        --from-file='./dashboards/00 - Overview/global-volume.json' \
        --dry-run=client \
        -o yaml \
    | kubectl label -f- --dry-run=client -o yaml --local grafana_dashboard=1 \
    | kubectl annotate -f- --dry-run=client -o yaml --local 'grafana_folder=/tmp/dashboards/00 - Overview' \
    | kubectl apply --server-side=true -f -

    To help you import all the dashboards while preserving the recommended folder structure, a kustomize file is included in the bundle. Apply it with this command:

    kubectl kustomize ./ | kubectl apply -n <YOUR-NAMESPACE> --server-side=true -f -

  3. Enable and configure the dashboards sidecar container in Grafana’s values.yaml file:

    sidecar:
  dashboards:
    enabled: true
    label: grafana_dashboard
    label_value: '1'
    folderAnnotation: grafana_folder
    provider:
      name: 'Gradle Develocity Dashboards'
      type: file
      allowUiUpdates: false
      disableDeletion: true
      foldersFromFilesStructure: true

    For more information, refer to Grafana’s Helm installation guide and the Helm chart documentation.

Manually Importing Dashboards via the Grafana UI

Use if you only need a small subset of the provided dashboards, and you can’t use any of the more automated methods described above.

 You need the Editor role in Grafana to import dashboards via the UI.

Steps:

  1. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in Prerequisites.

  2. Go to your Grafana’s dashboard view at https://grafana.example.com/dashboards.

  3. Optional: create a new folder for the Gradle dashboards by clicking New and selecting Create Folder.

  4. Click New and select Import.

  5. Drag the JSON file of the dashboard you want to import into the drop zone, or click the drop zone to open a file dialog, then click Load.

  6. Confirm the name of the dashboard and the folder you want to import it into, then click Import.

Using Amazon Managed Grafana With Terraform

Use if you want to use Amazon Managed Grafana, and you manage your infrastructure with Terraform.

This only deploys the Amazon Managed Grafana instance and imports the dashboards. It requires an already working Athena setup to succeed. Amazon Managed Grafana uses either AWS IAM Identity Center or SAML. The provided Terraform scripts only support IAM Identity Center. If you want to use SAML, adjust the Terraform modules in terraform/modules/develocity-drv-aws-grafana-athena/grafana.tf accordingly.

The bundle includes a set of Terraform modules and scripts that create and populate an Amazon Managed Grafana instance along with the required permissions, buckets, and other ancillary resources. These modules live in the terraform/modules directory and can be integrated into your existing infrastructure as code pipeline.

The shell scripts used in the following steps are provided as a convenience. You can also use them as a reference for integrating the Terraform modules into your existing infrastructure as code pipeline.

Steps:

  • Ensure you have the AWS CLI installed and configured with the necessary permissions.

  • Make sure you have Terraform installed.

  • Decompress the bundle and navigate to the terraform directory. Every subsequent step should be executed in this directory.

  • The terraform directory contains three shell scripts used in the steps below:

    • provision-grafana.sh deploys the Amazon Managed Grafana instance and its required resources.

    • provision-grafana-datasources.sh installs the Athena plugin and creates the Athena data source.

    • provision-drv-dashboards.sh imports the dashboards.

Prepare Your Environment

unzip gradle-dashboards-bundle-X-X-X.zip

Change your working directory to the terraform directory of the unzipped bundle:

cd terraform

Provision the Amazon Managed Grafana Instance

The provided modules assume you use AWS IAM Identity Center to manage the users and groups that have access to the Amazon Managed Grafana instance. In that case, a set of user and group SSO IDs is required to set up the Grafana instance. These IDs aren’t the same as AWS user IDs: they must be retrieved from the AWS SSO console. Contact your AWS SSO administrator to get them.

Run the provision-grafana.sh script to deploy the Amazon Managed Grafana instance and its required resources.

provision-grafana.sh \
    --bucket-name develocity \(1)
    --aws-region eu-west-1 \(2)
    --aws-profile my-profile \(3)
    --develocity-drv-grafana-admin-user-ids my-sso-id \(4)
    --develocity-drv-grafana-admin-group-ids my-sso-id \(4)
    --prefix develocity \(5)
    --apply \ (6)
    --destroy (6)
1 The bucket name where your build models are stored. This is usually the same bucket as the one configured for Develocity.
2 The region where you want to deploy the Amazon Managed Grafana instance.
3 The name of the AWS CLI profile you want to use to deploy the resources.
4 The SSO IDs of the groups or users you want to have admin access to the Grafana instance. This is a repeatable argument. At least one of these arguments must be provided.
5 An optional prefix for the resources created by the script. This is useful for avoiding naming conflicts when deploying to the same AWS account.
6 To apply or destroy the resources respectively. If neither is provided, the script defaults to creating a Terraform plan. In either case you still need to interactively approve the plan before it is applied.

Install the Athena Plugin and Create the Athena Data Source

Once the Amazon Managed Grafana instance is deployed, install the Athena plugin and create the Athena data source by running provision-grafana-datasources.sh:

provision-grafana-datasources.sh \
    --db-name develocity-db \(1)
    --grafana-URL https://my-grafana-URL.com \(2)
    --grafana-token my-grafana-token \(3)
    --workgroup develocity-wg \(4)
    --aws-region eu-west-1 \(5)
    --apply \(6)
    --destroy (6)
1 The name of the Glue database where the Athena tables were created.
2 Optional parameter, normally provided by the previous script automatically. The URL of the Amazon Managed Grafana instance.
3 Optional parameter, normally provided by the previous script automatically. The API token for the Amazon Managed Grafana instance.
4 Optional parameter, normally provided by the previous script automatically. The name of the Athena workgroup.
5 Optional parameter, normally provided by the previous script automatically. The region where the Amazon Managed Grafana instance was deployed.
6 To apply or destroy the resources respectively. If neither is provided, the script defaults to creating a Terraform plan. In either case you still need to interactively approve the plan before it is applied.

Import the Provided Dashboards

Finally, import the dashboards into the provisioned Grafana instance by running provision-drv-dashboards.sh:

provision-drv-dashboards.sh \
    --dashboard-folder-path ../../../dashboards \(1)
    --grafana-URL https://my-grafana-URL.com \(2)
    --grafana-token my-grafana-token \(3)
    --datasource-id my-datasource-id \(4)
    --apply \(5)
    --destroy (5)
1 The path to the directory containing the dashboard JSON files. If you are using the provided bundle, this is ../dashboards.
2 Optional parameter, normally provided by the previous script automatically. The URL of the Amazon Managed Grafana instance.
3 Optional parameter, normally provided by the previous script automatically. The API token for the Amazon Managed Grafana instance.
4 Optional parameter, normally provided by the previous script automatically. The ID of the data source created in the previous stage.
5 To apply or destroy the resources respectively. If neither is provided, the script defaults to creating a Terraform plan. In either case you still need to interactively approve the plan before it is applied.

For security reasons, the lifetime of the Grafana token used to configure the Amazon Managed Grafana instance is limited. If the token expires, AWS returns Access denied errors when applying the Terraform plans. To fix this, rerun the provision-grafana-datasources.sh script with the --apply flag to generate a new token. This doesn’t affect any of the previously deployed resources.

If the script executions fail for some reason, run terraform output stages/stage_name to get the outputs of the executed stage. Alongside the Grafana URL and the administrator token, this provides valuable information for investigating the failures.

Required AWS Permissions

Deploying an Amazon Managed Grafana instance requires many permissions, because it’s a complex operation involving several resource types. The permissions and AWS-managed policies that must be attached to the user or role executing the Terraform scripts are listed below.

  • Permissions required for managing IAM resources

    • These permissions are required to manage the role that can be assumed by the managed Grafana instance, which has access to the bucket storing the build-model data used by Athena.

    • iam:ListRoles

    • iam:CreateRole

    • iam:GetRole

    • iam:DeleteRole

    • iam:ListRolePolicies

    • iam:ListAttachedRolePolicies

    • iam:ListInstanceProfilesForRole

    • iam:AttachRolePolicy

    • iam:PutRolePolicy

    • iam:GetRolePolicy

    • iam:DeleteRolePolicy

    • iam:DetachRolePolicy

  • AWS managed policy required to manage S3 connections

    • This policy is required to create and manage a bucket that stores the query results executed by Athena.

    • AmazonS3FullAccess

  • AWS managed policy required to manage Athena resources

    • This policy is required to create and manage the Athena workgroup and the Athena database.

    • AmazonAthenaFullAccess

  • AWS managed policy required to administer the Amazon Managed Grafana instance

    • This policy is required to create and manage the Amazon Managed Grafana instance.

    • AWSGrafanaAccountAdministrator

  • AWS managed policies to manage the SSO settings

    • These policies are required to manage the SSO settings for the Amazon Managed Grafana instance.

    • AWSOrganizationsFullAccess

    • AWSSSODirectoryAdministrator

    • AWSSSOMasterAccountAdministrator

Upgrading

When you upgrade Develocity, new data becomes available and new dashboards may be added to surface more insights.

Upgrading replaces every Gradle-provided dashboard. If you have created your own dashboards, or imported the bundle into a Grafana instance that holds other dashboards, make sure you only remove the dashboards supplied by Gradle.

How you deploy the new set of dashboards depends on how you originally installed them, so follow the instructions for your Grafana installation type.

Upgrading Dashboards Provisioned With the Built-in Mechanism

If you installed the dashboards as described in Using the Built-in Grafana Provisioning Mechanism, upgrade them as follows:

  1. Open your Grafana provisioning folder.

  2. Delete all folders and files you want to update within the folder.

    In a Docker Desktop environment, this may cause Docker to stop syncing changes. If that happens, restart the container, delete the files one by one, or enable File Sharing in your Docker Desktop settings.

  3. Open Grafana and log in with an account that has edit privileges.

  4. Open the Dashboards view and select the checkbox next to the Name header to select all folders.

    Example of Selecting All Dashboard Folders by Name
    Example of Selecting All Dashboard Folders by Name

  5. Click Delete. This removes all dangling folders from the Grafana UI that can’t be automatically unprovisioned.

  6. Download the latest bundle from Downloads.

  7. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in Prerequisites.

  8. Copy the contents of the dashboards folder from the bundle into a directory on your Grafana server.

  9. Restart your Grafana instance to apply the changes.

Upgrading Dashboards Provisioned With Helm and Kubernetes

If you installed the dashboards as described in Using Grafana Provisioning With Helm and Kubernetes, upgrade them as follows:

  1. Delete the ConfigMaps containing the dashboards.

    kubectl --namespace <YOUR-NAMESPACE> delete configmap -l grafana_dashboard=1

  2. Open Grafana and log in with an account that has edit privileges.

  3. Open the Dashboards view and select the checkbox next to the Name header to select all folders.

    Example of Selecting All Dashboard Folders by Name
    Example of Selecting All Dashboard Folders by Name

  4. Click Delete.

  5. Download the latest bundle from Downloads.

  6. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in Prerequisites.

  7. Run the kustomize file included in the bundle to re-import the dashboards.

    kubectl kustomize ./ | kubectl apply -n <YOUR-NAMESPACE> --server-side=true -f -

Upgrading Manually Imported Dashboards

If you imported the dashboards as described in Manually Importing Dashboards via the Grafana UI, upgrade them as follows:

  1. Open Grafana and log in with an account that has edit privileges.

  2. Open the Dashboards view and select the checkbox next to the Name header to select all folders.

    Example of Selecting All Dashboard Folders by Name
    Example of Selecting All Dashboard Folders by Name

  3. Click Delete.

  4. Download the latest bundle from Downloads and follow the installation procedure again.

Upgrading Amazon Managed Grafana Installed With Terraform

If you installed Amazon Managed Grafana as described in Using Amazon Managed Grafana With Terraform, download the latest bundle from Downloads and follow the installation procedure again, using the path of the newly downloaded dashboards.

 Upgrading the Athena tables and views is a separate step, covered in Upgrading Athena Tables in the Amazon Athena user manual.