Unleashing your Instana to observe new technologies

Instana’s custom dashboard feature and OpenTelemetry integration allow users to adapt Instana for observing new systems or technologies. By leveraging public dashboards and reusable integration packages, users can implement observability solutions by themselves independently.

Exploring the public dashboards

Search for reusable dashboards on a central registry such as npmjs. These dashboards, bundled into integration packages, can be explored for their functionality, installation details, and other resources before integrating them into your Instana environment. This ensures a faster adoption of new observability features. IBM, along with customers and business partners, can provide their integration packages that can be downloaded and imported to enhance monitoring capabilities. The following table summarizes some available packages as examples:

Name	Description	Link
opentelemetry-demo	The Instana integration package used to demonstrate the monitoring of the OpenTelemetry demo application, an Instana version of the opentelemetry-demo project forked from the community.	opentelemetry-demo
go	The Instana integration package used to support Go monitoring.	go
nodejs	The Instana integration package used to support Node.js monitoring.	nodejs

Downloading and importing the dashboards

Now that the reusable dashboards are bundled into integration packages and publicly available, anyone can choose the packages that support the systems or technologies they want to observe, then download the packages and import into their existing Instana environments. This will immediately extend the capabilities of an Instana environment to support the observability of new systems or technologies.

There is a command line tool available to support the dashboards download and import. It is called the Instana CLI for integration package management. With this tool, you can manage the lifecycle of the package including the reusable dashboards. To download the latest version of the tool, see the Instana CLI for integration package management release page.

Downloading the dashboards

To download an integration package including the reusable dashboards by using the tool, you must specify the package name. For example, the following command downloads a package named @instana-integration/go:

$ stanctl-integration download --package @instana-integration/go

By default, the tool creates a sub-directory in the current working directory as the root directory to store all the downloaded integration packages. You can also specify your own root directory for the packages using the --location option. For example, the following command downloads the package under the root directory ./my-packages:

$ stanctl-integration download --package @instana-integration/go --location ./my-packages

Importing the dashboards

Once the integration package is downloaded to your local machine, you can use the tool to import the dashboards into any existing Instana environment. This requires you to provide the Instana server address and the API token using the corresponding options when running the tool. Typically, the tool calls a series of Instana APIs to complete the import of the dashboards. This is why it requires the API token. For example:

$ stanctl-integration import --package @instana-integration/go \
  --server $INSTANA_SERVER \
  --token $API_TOKEN

You can specify the directory using --location option. For example:

$ stanctl-integration import --package @instana-integration/go --location ./my-packages \
  --server $INSTANA_SERVER \
  --token $API_TOKEN

In order to make the import work, you must make sure that the API token enabled the permission Sharing custom dashboards publicly with all users and API tokens. To confirm this, you can navigate through Settings > Team Settings > API Tokens, starting from the left side of the navigation menu on Instana UI, then on the API Tokens page, select the token that you are using for the import. On the Edit API Token dialog, find the Owner Permissions section and make sure the Sharing custom dashboards publicly with all users and API tokens item is enabled.

Specifying parameter values for the dashboards

Some dashboards might have parameters in their dashboard definitions included in the integration package. This is because some values appeared in the dashboard definitions might not be determined yet when the dashboard maintainer defines the dashboard. You can check the package's home page to see if any parameters are included in this package. When importing such dashboards by using the tool, you can specify the actual values for these parameters by using --set option, and this option can be used multiple times. For example:

$ stanctl-integration import --package @instana-integration/go \
  --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --set key1=value1 \
  --set key2=value2