Making your Instana dashboards publicly shareable

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, see Building custom dashboards.

Once you have your dashboard ready, click the Options overflow menu and select Edit as JSON. Then, copy the dashboard definition content in the "Edit Dashboard" dialog, and save as a local file for further processing.

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

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

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

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

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. Before you publish the package, you can run the lint command to verify that the package follows the proper conventions and standards.

The lint command helps ensure that the required package metadata is in place, the documentation is correct, and the dashboard files are valid. It also provides detailed error or warning messages for linting failures, with debug information if enabled. See the following example:

# navigate to the folder of the package you want to lint
$ stanctl-integration lint

# Linting with a specific package path
$ stanctl-integration lint --path /path/to/package

# Linting with debug mode enabled
$ stanctl-integration lint --debug

After you verify that your integration package meets all the necessary standards with lint, the next step is to publish your package to the central registry. Publishing your package allows others to explore, download, and import it into their environments. To make it simple, the Instana CLI for integration package management 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>

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