Creating Instana integrations

Before you begin

Ensure that you have following information to hand:

• Endpoint
• API Token
• Filters to define subsets of data that is pulled from Instana (optional)

Creating Instana integrations

To create an Instana integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. On the Integrations page, click Add integration.

4. From the list of available integrations, find and click the Instana tile.

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

5. On the side-panel, review the instructions and click Get started.

6. On the Add integration page, define the general integration details:

   • Name: The display name of your integration.

   • Description: An optional description for the integration.

   • Endpoint: Enter an endpoint for the integration.

   • API token: Enter an API token for the integration. 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 integration, you will be provided with a bootstrap command to finish the deployment.

   • Test connection: click to see is the connection can be established.

     

     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 integration.

7. Click Next.

8. If you would you like to optionally use an HTTP proxy configuration with the Instana integration, enter the following Configure proxy information:

   • Proxy URL: Enter the URL or domain name of the Proxy Server including the protocol. Do not include the port in the Proxy URL field.

   • Proxy Port: Enter the port as a number in the Proxy Port field.

   • Proxy Username: If the HTTP proxy server requires authentication, enter the proxy username. If not, you can leave this field blank to use the proxy without authentication.

   • Proxy Password: If the HTTP proxy server requires authentication, enter the proxy password. If not, you can leave this field blank to use the proxy without authentication.

     

   Note: An HTTPS proxy server and certificate authentication are not supported for the proxy configuration. Only basic authentication (username and password) or no authentication with an HTTP proxy server are supported.

9. Click Next.

10. Enter the following Collect topology data information:

    • Enable data collection: Enable the toggle button.

    • Time window (seconds): Reference the windowSize within the Instana API.

    • Integration interval (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 AIOps applications: Enable the toggle button (if required).

      Note: When this toggle button is enabled, an IBM Cloud Pak for AIOps 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 IBM Cloud Pak for AIOps 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.

11. Click Next.

12. 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

13. Click Next.

14. 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.
      • 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.

15. Click Next.

16. 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 integration 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.
    • Scheduled collection 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.

      • Scheduled collection 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 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 integration, you cannot edit it. If you need to edit either of these properties, you must delete your integration and create a new one.

17. Click Done.

For more information about performance considerations for metric data collection, see Performance considerations for metric data collection.

You have created an Instana integration in your instance.

After the integration creation is complete, and if you selected the Remote option for integration deployment, you can download the bootstrap script. Select the created integration, 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 integration.

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

• Podman needs to be installed on the remote cluster.
• Log in to the Image registry for the script to pull in the image by using the Podman login command.

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

To create more integrations (such as a ChatOps integration), see Configuring Integrations.

For more information about working with the insights provided by your integrations, 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 toward either end of the spectrum (for instance, if you have mostly hosts that define the most metrics), then the formula might underestimate the required limit.

To determine the number of resources (snapshots) for each infrastructure pluginAPI, you can use the following:

api/infrastructure-monitoring/snapshots?plugin=technology_name

Example:

api/infrastructure-monitoring/snapshots?plugin=host

For more information about Instana APIs, see Instana API.

With the following example curl commands, you can retrieve the number of the following resources:

• snapshots-for-selected-technologies (such as host)

  curl -k -s --request GET 'https://<instana server hostname>/api/infrastructure-monitoring/snapshots?plugin=host' --header 'Authorization: apiToken <api token>' | jq '.items|length'
  

• number-of-application-perspectives

  curl -k -s --request GET 'https://<instana server hostname>/api/application-monitoring/applications' --header 'Authorization: apiToken <api token>' | jq '.items|length'
  

• number-of-services

  curl -k -s --request GET 'https://<instana server hostname>/api/application-monitoring/services' --header 'Authorization: apiToken <api token>' | jq '.items|length'
  

Enabling and disabling Instana integrations

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

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. On the Manage integrations tab of the Integrations page, click the Instana integration type.

4. Click the integration 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 an integration does not delete the integration.

You have enabled or disabled your integration. For more information about deleting an integration, see Deleting Instana integrations.

Editing Instana integrations

After you create your integration, you can edit it. To edit an integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. Click the Instana integration type on the Manage integrations tab of the Integrations page.

4. On the Instana integrations page, click the name of the integration that you want to edit. Alternatively, you can click the options menu (three vertical dots) for the integration and click Edit. The integration configuration opens.

5. Edit your integration as required. Click Save when you are done editing.

   

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

Deleting Instana integrations

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

To delete an integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. Click the Instana integration type on the Manage integrations tab of the Integrations page.

4. On the Instana integrations page, click the options menu (three vertical dots) for the integration that you want to delete and click Delete.

5. Enter the name of the integration to confirm that you want to delete your integration. Then, click Delete.

Your integration is deleted.