Authored by @Ying Mo, @Paras Kampasi @Roger Kuo @Yanwei Li
In the previous blog post, we discussed the following: 1) how OpenTelemetry and Instana’s custom dashboards can be combined to help extend Instana’s observation capabilities to support new systems and technologies; 2) how reusable dashboards can be bundled into integration packages; 3) where to search for and explore these packages; and 4) how to download and import the sharable packages using the Instana CLI for Integration Package Management tool. In this blog post, we will discuss the steps on how to make custom dashboards publicly sharable so that they can be downloaded and imported by other people.
Define your own sharable dashboard
To make a dashboard publicly sharable, the dashboard must first be defined via Instana’s custom dashboard feature. To create a custom dashboard, navigate through Custom Dashboards from the left-hand side navigation menu to reach the My Custom Dashboards page. Click the Add dashboard button on the top-right corner, give the dashboard a name, and then click the Create button. This will create an empty dashboard. Widgets can be added to the dashboard by clicking the Add Widget button at the top-right corner.
Once the dashboard is ready for export, select Edit as JSON from the dropdown menu at the top-right corner, and then copy and save the JSON content in the Edit Dashboard dialog as a local file. For more information on how to build custom dashboards, please refer to the Instana product documentation.
Parameterize your dashboard
When defining a custom dashboard, the dashboard may have extra parameters in its definitions. This is caused when certain values within the dashboard are not properly defined. Consider MongoDB as an example. When multiple MongoDB instances are being monitored, each instance should have its own dashboard, as there may be variations in the data. An unsuspecting user may use one instance’s dashboard to visualize a separate instance and end up with undefined data values.
Below is an example to demonstrate this situation. Within the JSON of a defined dashboard is a section for widgets. The sample widget is used to display a pie chart of calls made to the MongoDB instance. To differentiate the data coming from different instances, a filter is defined in the widget to select data by a tag named service.name, where the tag value is the instance name. Since the actual name will vary for each instance, the tag value must be modified to accommodate all instances. By using {{ service.name }} as the tag value, all instances can be represented, thus allowing the dashboard to be reusable.
"widgets": [
{
"id": "mOnzaM7NQRQQGKwt",
"title": "Calls to Mongo",
"width": 3,
"height": 15,
"x": 0,
"y": 4,
"type": "pie",
"config": {
"shareMaxAxisDomain": false,
"y1": {
"formatter": "number.detailed",
"renderer": "pie",
"metrics": [
{
"includeSynthetic": false,
"color": "",
"metric": "calls",
"timeShift": 0,
"tagFilterExpression": {
"name": "service.name",
"type": "TAG_FILTER",
"value": "{{ service.name }}",
"entity": "DESTINATION",
"operator": "EQUALS"
},
Then, when users are importing a dashboard, they can specify the actual value of this parameter in the command line using the --set option. And the dashboard can be imported multiple times, each time with different parameter values. For example:
$ stanctl-integration import --package @instana-integration/mongo \
--server $INSTANA_SERVER \
--token $API_TOKEN \
--set service.name=my-instance-1
$ stanctl-integration import --package @instana-integration/mongo \
--server $INSTANA_SERVER \
--token $API_TOKEN \
--set service.name=my-instance-2
Access rules
Other dashboard definition tweaks may be necessary before the dashboard can be publicly sharable. For example, the access rules of the dashboard are by default set to private.
{
"id": "K9v_xrJCSCKvgvbhhR2ThA",
"title": "Mongo Monitoring",
"accessRules": [
{
"accessType": "READ_WRITE",
"relationType": "USER",
"relatedId": "65a513ac36d1a00001d03c71"
}
],
The access rules must be modified for the dashboard to be public. To do so, locate the accessRules field, remove any private rules, then add the public rule as shown below:
{
"id": "K9v_xrJCSCKvgvbhhR2ThA",
"title": "Mongo Monitoring",
"accessRules": [
{
"accessType": "READ",
"relationType": "GLOBAL",
"relatedId": ""
}
],
Package your dashboard
Instana integration package
After the dashboard has been set to be publicly shareable, the dashboard will need to be bundled into an Instana integration package. This package packs various Instana integration elements into a single file that can be easily published, downloaded, and imported. Users may choose to either manually create the package or use the CLI tool to automate the process. The following is an example of the folder structure:
Each Instana integration package starts with a directory named after the package. This directory should contain a package.json file containing essential information about the package, a README.md file containing a description about the package, and a subdirectory called dashboards which contains all the dashboard definition files.
For official IBM releases, packages should be labeled as @<org-name>/<sys-name>, where <org-name> is the IBM organization name, and <sys-name> is the system or technology supported by the package. For the purposes of Instana dashboards, use @instana-integration as the organization name. All packages released under IBM fall under a directory named after the organization, and each package will have its own subdirectory. For example:
The package.json file
The package.json file contains essential information about the Instana integration package, including its name, version, description, and author. This metadata helps identify the package and its details. The following is an example of how the file looks:
{
"name": "my-awesome-xyz-integration",
"version": "1.0.0",
"description": "The Instana integration package for my awesome xyz monitoring.",
"author": "morningspace",
"license": "MIT",
"scripts": {},
"keywords": [
"instana",
"integration",
"package",
"xyz",
"monitoring"
]
}
Manual package creation will require users to update the fields with appropriate values. An example can be seen in the next subsection.
Init the package using CLI
The Instana CLI for Integration Package Management tool provides an init command to streamline the package initialization process. This command will prompt the user for some necessary information needed to build the package. To run the init command:
$ stanctl-integration init
The following is sample input for a package released under 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
Upon completion, the tool will generate a skeleton file structure for the new integration package. The following is an example:
$ tree @instana-integration
@instana-integration
└── go
├── README.md
├── dashboards
└── package.json
3 directories, 2 files
The following is an example of a package.json file generated by the CLI:
$ cat @instana-integration/go/package.json
{
"name": "@instana-integration/go",
"version": "1.0.0",
"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.",
"author": "IBM",
"license": "MIT",
"scripts": {},
"keywords": [
"ibm",
"instana",
"custom dashboard",
"opentelemetry",
"go",
"monitoring"
]
}
After the package skeleton is created, either manually or via the CLI tool, move all the dashboard definition files into the dashboards subdirectory. Update the README.md file to include any essential information.
Publish your dashboard
Publish package using CLI
Once the package is ready, it can be published. This can be done using the CLI tool with the publish command. The command will require the package name and registry username and email. Alternatively, the directory path of the package can be used in place of the package name. The registry username and email should be the same as the credentials used during signup to a central registry such as https://www.npmjs.com/. Below is an example:
$ stanctl-integration publish --package @instana-integration/go \
--registry-username <your_username> --registry-email <your_email>
Upon using the publish command for the first time, the user will be directed to a web browser to login to the central registry. Login information will be stored in a local .npmrc file. By doing so, subsequent uses of the publish command will no longer require manual user login. If the CLI tool outputs a success message, the user should be able to locate the published package on the central registry website.
Contribute to observability-as-code repository
IBM has a GitHub repository to host all official integration packages: https://github.com/instana/observability-as-code. This is a public repository open to the community. Users can use these packages as references when creating their own packages, and they may also contribute their packages to the repository. The Instana team welcomes all contributions to this repository.
To contribute to the repository, the user will first need to fork the repository. After adding the package files, the user will need to submit a pull request. The Instana team will handle the request review and merging process. After the request is merged, a pipeline will publish the user package to the central registry. Upon completion, the package will be available as a part of the IBM collection of packages.
Import from local package
When importing a package, a user may decide to use a local package instead of pulling one from a registry. This may be reasonable, for example, if a user wants to test a package while avoiding the overhead of publishing and downloading. The CLI tool supports this use case. In this case, the user can provide the directory path of the package for the --package option. For example:
$ stanctl-integration import --package path/to/your/package \
--server $INSTANA_SERVER \
--token $API_TOKEN
Conclusion
This blog post explores all the necessary steps to publish custom dashboards. To recap:
A custom dashboard needs to be defined in Instana. After saving and modifying the dashboard definition file, it can be bundled into an Instana integration package and then published to a central registry. Packages can be created and published via the CLI tool. The CLI tool streamlines the process by helping create a skeleton package and by directly publishing the package to a central registry. Alternatively, a user can manually bundle a package and push it into IBM’s GitHub repository, whereupon the package will be automatically published on the user’s behalf.
The Instana team welcomes and encourages all community contributions to the IBM repository!
#CustomDashboards
#General
#OpenTelemetry
#Integration
#Tutorial