Making your Instana dashboards publicly shareable

Creating a custom dashboard

In order to make your dashboard publicly shareable, you need to define the dashboard first. This can be done by leveraging the Instana custom dashboard feature. For more information on how to build custom dashboards, please refer to Building custom dashboards.

Once you have your dashboard ready, you can select the Edit as JSON menu item from the dropdown on the top-right corner, then copy the dashboard definition content in the Edit Dashboard dialog, and save as a local file for further processing.

Parameterizing your dashboard

When defining a dashboard, you may have some parameters that can only be determined at runtime, such as the service name or service instance id. In order to make the dashboard reusable for other people, you can introduce placeholders to parameterize your dashboard. Using placeholders enhances the flexibility and adaptability of dashboards, making them suitable for a variety of environments and use cases. For example:

"tagFilterExpression": {
    "name": "service.name",
    "value": "{{ service.name }}"
}

This approach allows users to specify actual values for these placeholders during dashboard import. For instance, a user can import the same dashboard multiple times, each with a different service.name value:

$ stanctl-integration import --package @instana-integration/go \
  --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --set service.name=my-instance-1

$ stanctl-integration import --package @instana-integration/go \
  --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --set service.name=my-instance-2

Access rules

By default, the custom dashboard that you created is private, which means it is only visible to you. To make your dashboard publicly shareable, it is required to make it public, which means this dashboard is visible to everyone in your organization. To make the change, you can update the access rules in the dashboard definition. Locate the accessRules field, remove any private rules, then add a public rule as below:

"accessRules": [
    {
      "accessType": "READ",
      "relationType": "GLOBAL"
    }
]

Packaging your dashboard

The Instana CLI for integration package management provides an init command to streamline the package initialization process for you. It guides you through a series of questions to gather the necessary information based on your responses. Then, it generates the package directory structure, including subdirectories, along with a package.json and README.md file, providing a skeleton for your new integration package. To run the init command:

$ stanctl-integration init

The following sample input is for a package released by IBM:

? Enter integration package name: (e.g.: @instana-integration/nodejs, my-awesome-xyz-integration):  @instana-integration/go
? Enter integration package version:  1.0.0
? Enter integration package description:  The integration package is used to support Go monitoring. Once you import this package into your Instana environment, you will be able to monitor Go runtime and the applications on various aspects by checking the dashboards, alerts, etc. included in this integration package.
? Enter integration package keywords (comma-separated):  ibm,instana,custom dashboard,opentelemetry,go,monitoring
? Enter integration package author:  IBM
? Enter integration package license:  MIT
? Select the types of integration to be included in the package: dashboards

After you finish answering all the questions, the CLI generates the following directory structure, including package.json, README.md, and an empty dashboards subdirectory where you can put your dashboard definition files:

$ tree @instana-integration
@instana-integration
└── go
    ├── README.md
    ├── dashboards
    └── package.json

3 directories, 2 files

Publishing a package

After you create your package skeleton either manually or with the preceding CLI commands, you can put your dashboard definition files in the dashboards directory. After they are ready to be publicly shareable, you can publish the package to the central registry so that other people can explore, download, and import it. To make it simple, the Instana CLI for integration package management also provides a command publish to help users publish their packages.

To publish the package by using the CLI, you must specify the package name or the path to the package, the registry username, and email. If the package belongs to an organization, then the package name must be prefixed with the organization name. The registry username and email are the information that you can collect when you sign up to the central registry, for example, https://www.npmjs.com/. They are required when the CLI logs in to the central registry before it can publish the package. See the following example:

$ stanctl-integration publish --package @instana-integration/go \
  --registry-username <your_username> --registry-email <your_email>

If it is your first time to run the publish command, it brings you to the web browser and asks for your log-in to the central registry.

Importing from a local package

Sometimes you might want to keep your integration package locally for testing. The CLI also supports a --package option that allows you to specify a path to the package. This is useful when you want to validate your package locally without publishing it.

For example, you can prepare your integration package in a local directory and use the following command to import it:

$ stanctl-integration import --package path/to/your/package \
  --server $INSTANA_SERVER \
  --token $API_TOKEN