monitoring-dashboard-samples: sharing Google Cloud Monitoring dashboards as JSON

What the repository holds

This repository contains samples that may be used with the Cloud Monitoring Dashboards API, and it lives under the GoogleCloudPlatform organisation with an Apache 2.0 licence.

The top level of the repository shows the shape of it. There are dashboards/, which is the collection of dashboard specifications themselves. There are alerts/, which sits alongside it and suggests the project covers alerting policies as well as dashboards. There is integrations/, and a dm/ directory. There is terraform/, which points at infrastructure as code for the environments the dashboards describe. There is dev-docs/, scripts/, and a .github directory.

The presence of terraform/ alongside dashboards/ is the interesting pairing. A dashboard specification is only meaningful against a real deployment, because the metrics filters and the resource types in it refer to actual projects, instances and metrics that have to exist. Shipping the infrastructure definition alongside the dashboard means a reader can see what the dashboard was designed to show rather than staring at a JSON file with no context.

The primary language of the repository is recorded as TypeScript, which fits a repository whose scripts are thin wrappers around a REST API and whose tooling is a matter of gluing gcloud and curl together rather than writing anything substantial.

The last push was on 2026-10-15 and the repository publishes no GitHub releases. That is unsurprising for a collection of configuration files rather than a library, and it also means there is no version to pin: you take the state of the dashboards directory as it is.

The project is Apache 2.0, which is worth contrasting with the readme's tone. This is a Google-owned sample repository, the kind that tends to accumulate over years, and the practical question of whether the dashboards still match current API behaviour is something you check rather than assume.

Importing a dashboard, two ways

The readme gives two routes for importing, and the second one is more instructive than the first.

The script route sets two environment variables and runs a shell script:

    export PROJECT_ID=<PROJECT_ID>

    export FILE_NAME=<DASH_FILE_NAME>

    scripts/dashboard/dashboard.sh import $PROJECT_ID $FILE_NAME

The alternative is a direct curl call to the API, and the readme points at the projects.dashboards.create reference for the details:

curl -X POST -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://monitoring.googleapis.com/v1/projects/[project-id]/dashboards -d @[file-name.json]

That one line contains several decisions worth copying. The bearer token is not a static credential, it is obtained by calling gcloud auth application-default print-access-token, which means the request uses the same identity as whatever is already configured on the machine, whether that is a developer account or a service account in a CI environment. The request body is the JSON file piped in with the @ prefix, so the sample specification is uploaded verbatim with no transformation. And the URL is the REST endpoint for creating a dashboard in a project, so the operation is a plain create against the monitoring API.

The pairing of a friendly script and a raw curl is a good pattern for a sample repository. The script is what you use, the curl is what you read when you want to know what the script is doing, and the curl is what you paste into another environment where the script does not exist.

The readme also points at Cloud Shell, with a button that opens the project with the repository already cloned. For a sample repository whose whole purpose is to be run once to see what the output looks like, that is the fastest possible entry point, since the authentication and the gcloud CLI are already there and configured for the user's own project.

Exporting a dashboard you already built

The readme also covers the reverse direction, and this is the more useful half for most people.

The first step is to create the dashboard in the Monitoring UI, or as the readme says, even better, to share one you have already developed and used. That parenthetical is the advice that matters. A dashboard that someone spent a week on and has been running against real traffic is worth far more than a dashboard assembled to fill a slot, and the readme is nudging contributors towards the former.

Then you open the dashboard and copy the dashboard ID from the URL, the string after the /monitoring/dashboards/custom/ prefix. The readme gives a worked example, 10768789961894600977 in a URL that also carries a project id and a time domain parameter:

https://console.cloud.google.com/monitoring/dashboards/custom/10768789961894600977?project=sd-uxr-001&timeDomain=1h

Then you set three environment variables, DASH_ID, PROJECT_ID and FILE_NAME, and export it:

    export DASH_ID=<YOUR_DASH_ID>

    export PROJECT_ID=<PROJECT_ID>

    export FILE_NAME=<DASH_FILE_NAME>

    scripts/dashboard/dashboard.sh export $DASH_ID $PROJECT_ID $FILE_NAME

So the same script handles both directions, with the subcommand and the argument order changing. Import takes a project and a file, export takes a dashboard id, a project and a file.

The export step is the interesting one because it is how you get a dashboard out of the console as a portable artefact. The Cloud Console dashboard editor is a GUI with no notion of a file, and the JSON is the API's representation of a dashboard. So exporting means asking the API for the configuration the console sent, and writing it to disk in a form somebody else can import.

That round trip is the real value of this repository. A team can build a dashboard in the console, export it, share it as a file, and another team can import it into their own project. The sample repository is where the shared ones live.

metadata.yaml, and how a sample gets into the console

The contributor guidelines are the part of this repository that reveals how it is actually governed, and the mechanism is a single YAML file per directory.

In order for sample dashboards to appear in the Cloud Console, the metadata.yaml file in the dashboard's directory needs to be updated to include any new dashboards being added. The top level of that file holds a single sample_dashboards: key, whose value is a list of dashboard objects, and the readme gives a worked Nginx example:

sample_dashboards:
  -
    category: Nginx
    id: overview
    display_name: Nginx Overview
    description: |-
      This dashboard has charts for viewing Nginx when monitored by [Google's Ops Agent](https://cloud.google.com/stackdriver/docs/solutions/agents/ops-agent/third-party/nginx#monitored-metrics), Request Rate, Current Connections, and Connections Rate from NGINX as well as charts of infrastructure related metrics for the running NGINX VMs: CPU % Top 5 VMs, Memory % Top 5 VMs, and NGINX VMs by Region for a count of VMs over time. 

      There is also a card with links to docs and Nginx logs in Cloud Logging.
    related_integrations:
      - id: nginx
        platform: GCE

The description uses markdown-formatted links only, and empty newlines are used for paragraph breaks. That restriction is worth understanding, because the console renders these strings in a limited subset of markdown, so the usual habit of using a heading or a list inside a description will not render.

The field table explains each key. category sets the group name the dashboard appears under in the Cloud Console. id should match the dashboard file name without the extension, which is the join between the metadata and the file. display_name is what users see in the samples list. description is the brief description of the dashboard and its contents.

related_integrations is optional and is a list of integrations which collect the metrics displayed on the dashboard. For an Ops Agent application integration, the platform code should be 'GCE'. The id should match the integration's id, and the version field is optional and is for the case where a dashboard requires a specific revision of an integration.

So the relationship is three-way. The dashboard JSON is the thing, the metadata.yaml is the catalogue entry, and the file name is the key that joins them. Getting the id wrong does not break the import, it just means the console gallery cannot find the file, and that is the kind of mistake a contributor will make once.

Screenshots, file names and the shape of a contribution

The naming rules for screenshots are more detailed than most, and they exist for a practical reason.

Please add a screenshot with your dashboard, and all screenshots should live in the same directory as the sample dashboard specification. The naming has two cases. If there is only a single screenshot, the name should match the dashboard specification but with a PNG extension, so cloudrun-monitoring.json pairs with cloudrun-monitoring.png. If there are multiple screenshots, a two digit number should be added between the name and the file extension, giving gke-cluster-monitoring.json with gke-cluster-monitoring.01.png and gke-cluster-monitoring.02.png.

The zero-padded two digit numbering is the detail that matters. It is there so the files sort correctly in a directory listing, which means the intended order of the screenshots is preserved when somebody browses the directory. A dashboard is often a scrollable set of panels, and the order in which the panels are read is part of the explanation of what the dashboard is for.

So a complete contribution is three things in one directory. The dashboard JSON specification, the metadata.yaml entry that catalogues it, and the screenshot or screenshots that show what it looks like. Plus a README.md in the same directory of the dashboard file, which the guidelines also ask you to update.

That last requirement is the one most likely to be forgotten, because a README in a per-dashboard directory is easy to overlook when you are thinking about adding a dashboard file and its screenshot. The rules about filenames and metadata are the ones a reviewer will check automatically; the README is the one a human has to remember.

The repository has both a CONTRIBUTING.md and a CODE_OF_CONDUCT.md at the top level, which is the standard pairing for a project that wants outside contributions.

Editorial conclusion

Adopt this repository if you want to start from a working Cloud Monitoring dashboard rather than building one from an empty canvas, or if you want to export a dashboard you have built so someone else can import it. Do not adopt it as a dashboard template gallery for other monitoring tools, because the JSON format is specific to the Cloud Monitoring Dashboards API. Before you commit, check the dashboards/ directory for something close to your stack, and read the contributor guidelines, because the metadata.yaml entry is what actually makes a dashboard appear in the Cloud Console rather than merely existing in the repository.

Frequently asked questions

Official sources

1. GoogleCloudPlatform/monitoring-dashboard-samples on GitHub
2. Issues
3. License: Apache-2.0
4. README