Creating Instana connections

You can integrate with Instana to enable connectivity to Instana events, metrics, and topology by using an Instana connection. Instana assets can be combined with IBM Cloud Pak for Watson AIOps AI, such as runbooks, metric anomaly detection, and log anomaly detection to help you gain insights.

If needed, you can create multiple Instana connections. This deployment model has only one topology processor and multiple Instana connectors. The topology processor treats each connector as a distinct topology provider.

The list of technologies is determined dynamically, based on the actual resources available in the Instana instance the connector is pulling metrics data from. Each technology includes a list of all available metrics that can be dynamically retrieved by the Instana connector. The connector also provides a set of recommended metrics to select from.

For more information about working with Instana connections, see the following sections:

Before you begin

Ensure that you have following information to hand:

Creating Instana connections

To create an Instana connection, complete the following steps:

  1. Log in to IBM Cloud Pak Automation console.
  2. Expand the navigation menu (four horizontal bars), then click Define > Data and tool connections.

  3. On the Instana section of the list, click Add connection.

    Note: If you do not immediately see the connection that you want to create, you can filter the list sections by type of connection. Click the type of connection that you want in the Category section.

  4. Enter the following Add connection information:

    • Name: The display name of your connection.
    • Description: An optional description for the connection.
    • Endpoint: Enter an endpoint for the connection.
    • API token: Enter an API token for the connection. The API Token can be fetched from the Instana web UI.

    • Deployment options: Select between the local or remote radio buttons. If you select remote, after adding the connection, you will be provided with a bootstrap command to finish the deployment.

      Note: To use the Instana API for the collection of Instana data (metrics, events, and topologies), an API token is required. These API tokens can be created on the Instana user interface. Click the Settings icon, then Team Settings > API Tokens, and lastly click Add API Token to create a new API token.

    The default configuration for a new API token is enough for this Instana Connector.

  5. Click Next.

  6. Enter the following Collect topology data information:

    • Enable data collection: Enable the toggle button.
    • Time window (seconds): Reference the windowSize within the Instana API.
    • Connection Intervals (seconds): Specify a time period for how frequently to run the job.
    • Application name allowlist pattern: Filter app perspective collection based on the name of the application.

    • Import Instana application perspectives as Cloud Pak for Watson AIOps applications: Enable the toggle button (if required).

      Note: When this toggle button is enabled, an IBM Cloud Pak for Watson AIOps AI Manager application for each application perspective in Instana is automatically created. If it is not turned on, then you create resource groups for only the services that are part of that application in Instana. So, you have the opportunity to define your own AI Manager applications, by adding your own group to the application. It's important to note that if the application is created automatically by enabling the toggle button, the application is not controlled by the user. It is the product itself that controls the application. Only if you create the application yourself can you control the lifecycle of the application, and thus remove or delete it.

  7. Click Next.

  8. Enter the following Collect event data information:

    • Enable data collection: Enable the toggle button if required.

    • Types of events: Select one or more event types for data collection from the following options:

      • Incidents
      • Issues
      • Changes

  9. Click Next.

  10. Enter the following Collect metric data information to define how you want to collect metric data. Topology metric data that is related to applications, endpoints, and services can be enabled and thus collected, or indeed disabled.

    • Enable data collection: Set the toggle button to 'on'.

    • Monitored metrics: You can select built-in metrics to monitor. These metrics are categorized by the technologies that they are associated with. You can also add custom-defined metrics to monitor. To select metrics, use any of the following options:

      • Enter your preferred metrics in the search bar and select their corresponding checkboxes.
      • Search and select your preferred technologies and their associated metrics in their respective filter table. To find the related metrics of a technology, click its corresponding arrow. By default, all metrics of the chosen technologies are selected.
      • Select the Start from recommended metrics checkbox if you are not sure which metrics to start with. This option selects all recommended technologies and their associated metrics in the filter table.

      Note:

      • Clear the selected checkboxes to undo any selection. However, if you clear the Start from recommended metrics checkbox, all current selection is cleared.
      • All selected metrics are listed in the Selected metrics list. You can remove any listed metric by clicking the Deselect Metric icon corresponding to it.
      • You might see performance issues or gaps in your data due to the number of metrics selected. To avoid this problem, consider starting with the set of recommended metrics or those that are most important for you to monitor.

  11. Enter the following Metric data summary information:

    • Selected metrics: The table lists all the selected technologies and metrics. You can remove any metrics from the list. To remove a listed metric, select the checkbox corresponding to it and click Remove.
    • Only collect Live Data once the connection is established: Select the checkbox to enable live data collection.
      Note: If you choose to collect only live data, you cannot collect historical data after the live data collection starts.
    • Aggregation interval (minutes): Enter a value in minutes. This value is the frequency at which data is collected.

    • Historical data collection: The recommended time period for collecting historical metric data is two weeks, though it is possible to collect it for up to 31 days. Enter a start and end date and time in the following formats:

      • Start date and time: Select the start date from the calendar and enter the time in the 'hh:mm' format (hours and minutes).

        Note: Your start date should not exceed 31 days from the present.

      • Time zone: Select your time zone from the dropdown list.

      • End date and time: Click Add end date and select a date from the calendar. Also, enter the time in the 'hh:mm' format (hours and minutes). If you don't want to set an end date at this stage, click Remove End Date.

      • Aggregation interval (minutes): Enter a value in minutes. This value is the frequency at which data is collected.

        Note: If you do not select an end date, IBM Cloud Pak for Watson AIOps collects historical data from the specified start date and continues with live data collection. You cannot collect historical data after live data collection starts.

        Note: If you have already set an end date and time for an Instana connection, you cannot edit it. If you need to edit either of these properties, you must delete your connection and create a new one.

  12. Click Done.

For more information about performance considerations when collecting metric data, see Performance considerations when collecting metric data.

You have created an Instana connection in your instance.

After the connection creation is complete, and if you selected the Remote option for connector deployment, you can download the bootstrap script. Select the created connection, and then click download from the options menu (three vertical dots). If a script is regenerated, it invalidates the credentials of previously downloaded scripts for that connection.

Note: You can either copy the script or download as an sh file to run it on a remote cluster.

Prerequisites before you run the bootstrap script on a remote cluster

After you create your connection, you must enable the data collection to connect your connection with the AI of IBM Cloud Pak for Watson AIOps. For more information about enabling your connection, see Enabling Instana connections.

To create more connections (such as a ChatOps connection), see Configuring data and tool connections.

For more information about working with the insights provided by your connections, see ChatOps insight management.

For Instana on-prem installation, the recommended rate limit is double the number of resources. This limit is enough to cover most cases, although situations might arise where the limits need to be increased even more. When a more precise way to determine the limit is required (for instance a shared multi-tenant SaaS environment), the following formula can be applied: 

number-of-metric-API-calls-per-hour ~= (number-of-selected-technologies x 2) x (snapshots-for-selected-technologies / 30) x (60 / collection-interval)
number-of-topology-API-calls-per-hour ~= (number-of-application-perspectives x (60 / collection-interval)) +(number-of-services x (60 / collection-interval))
number-of-events-API-calls-per-hour = 60

total= number-of-metric-API-calls-per-hour + number-of-topology-API-calls-per-hour + number-of-events-API-calls-per-hour

Note: This formula is not always 100% accurate, as each technology or plug-in has a different number of metrics collected (the mean value across these is used, which is 2 collection cycles or technology). If the environment is unbalanced towards either end of the spectrum (say you have mostly hosts, who happen to define the most metrics), then the formula might underestimate the required limit.

In order to determine the number of resources (snapshots) for each infrastructure pluginAPI, customers can use the following: 

api/infrastructure-monitoring/snapshots?plugin=technology_name

A practical example of which is 

api/infrastructure-monitoring/snapshots?plugin=host

For more information on Instana APIs, see Instana API.

The following example curl commands allow you to retrieve the number of:

Enabling and disabling Instana connections

If you didn't enable your data collection during creation, you can enable your connection afterward. You can also disable a previously enabled connection the same way. To enable or disable a created connection, complete the following steps:

  1. Log in to IBM Cloud Pak Automation console.
  2. Expand the navigation menu (four horizontal bars), then click Define > Data and tool connections.
  3. Click the Instana connection type in the Manage connections tab.
  4. Click the connection that you want to enable or disable.
  5. Go to the Collect topology data section. Enable the toggle button if required.
  6. Go to the Collect event data section. Enable the toggle button if required.
  7. Go to the Collect metric data section. Enable the toggle button if required.

Note: Disabling data collection for a connection does not delete the connection.

You have enabled or disabled your connection. For more information about deleting a connection, see Deleting Instana connections.

Editing Instana connections

After you create your connection, you can edit it. To edit a connection, complete the following steps:

  1. On the Instana connections page, click the options menu (three vertical dots) of the Instana connection that you want to edit.
  2. Click Edit. The connection configuration page opens.

  3. The Instana connection wizard guides you through the 4 steps that are involved, and you can make your edits as you go through this wizard.

    Note: While you can modify all other fields, you cannot alter the actual connection name at this stage, as it is already created and thus shows as read-only.

  4. Then, click Save to ensure that your edits are applied.

You have edited your connection. If you have not previously enabled or disabled your application, you can enable or disable the connection directly from the interface. For more information about enabling and disabling your connection, see Enabling and disabling Instana connections. For more information about deleting a connection, see Deleting Instana connections.

Deleting Instana connections

If you no longer need your Instana connection and want to not only disable it, but delete it entirely, you can delete the connection from the console.

To delete a connection, complete the following steps:

  1. On the Instana connections page, click the options menu (three vertical dots) of the corresponding connection that you want to delete.
  2. Click Delete. A message appears confirming that you're ready to delete your connection.
  3. Enter the name of the connection to confirm deletion.
  4. Click Delete.

Your connection is deleted.