Unleashing your Instana to observe new technologies

You can set up Instana to observe new systems or technologies by using Instana’s custom dashboard and events definition features, along with its OpenTelemetry integration capabilities. By using public dashboards, events, and reusable integration packages, you can implement the required observability solutions by yourself.

Exploring the integration packages

Search for reusable dashboards and events definition that are bundled into integration packages on a central registry such as npmjs. You can review these packages for their functionality, installation steps, and other details before you integrate them into your Instana environment. Reviewing the packages ensures a faster adoption of new observability features. IBM, along with customers and business partners, provide their integration packages that you can download and import to enhance the monitoring capabilities. The following table provides some examples of available packages:

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, importing, and exporting dashboards and events definition

Because the reusable dashboards and events definition are bundled into integration packages and publicly available, you can choose the packages that support the systems or technologies that you want to observe. Download the required packages and import them into your existing Instana environments. Importing the packages immediately extends the capabilities of your Instana environment to support the observability of new systems or technologies.

You can use the command-line tool, Instana CLI for integration package management, to download, import, and export the integration packages. With this tool, you can manage the lifecycle of the package including the reusable dashboards and events definition. To download the latest version of the tool, see the Instana CLI for integration package management release page.

Downloading dashboards and events definition

To download an integration package including the reusable dashboards and events definition by using the tool, you must specify the package name. See the following sample command to download 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 dashboards and events definition

Once the integration package is downloaded to your local machine, you can use the tool to import the dashboards and events definition into any existing Instana environment. You must provide the Instana server address and the API token by using the corresponding options when you run the tool. The API token is required because tool calls a series of Instana APIs to complete the import of the dashboards and events definition. See the following 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

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, open the Instana navigation menu and go to Settings > Team Settings > API Tokens, and 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

Exporting dashboards and events definition

In addition to downloading and importing, the Instana CLI for integration package management also supports exporting dashboards and events definition from an existing Instana environment. To export dashboards and events definition, you must provide the Instana server address, a valid API token, and at least one --include option that specifies the type of asset (dashboard or event). In addition to the asset type, you must specify either the title or id to identify the specific element you want to export. The tool uses the Instana APIs to retrieve the matching assets and saves them locally in a portable format. See the following example where dashboards and events definition are exported by matching a title:

$ stanctl-integration export --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --include type=dashboard title="dashboardTitle"

Alternatively, if you know the ID of a dashboard or event, you can export it directly by specifying the ID. See the following example:

$ stanctl-integration export --server $INSTANA_SERVER \
  --token $API_TOKEN \
  --include type=event id=eventID