App for Slack alert channel (public preview)

Edit online

You can create an App for Slack alert channel to send real-time alert notifications from Instana to that Slack channel.

Note: The IBM Instana App for Slack is now officially certified and listed in the Slack Marketplace. You can install it directly from the Slack Marketplace or through the Instana installation workflow that is described in this document.

Installation Prerequisites

Edit online

Instana currently supports only SaaS deployments. To proceed with installation, make sure that you have an active login session in Instana.

Creating an App for Slack alert channel

Edit online

To create an App for Slack alert channel, complete the following steps:

  1. From the navigation menu in the Instana UI, click Settings.

  2. On the Global settings tab, in the Events & alerts section, click Alert channels.

  3. Click Add alert channel.

  4. Select an App for Slack from the list.

  5. Enter a name for the Slack application alert channel.

    Figure 1. App for Slack alert channel
    App for Slack alert channel

    Display Emoji: Enable this option to convert emoji strings from Instana (for example, :warning:) into visual emojis when shown in Slack. If this option is disabled, the strings appear as plain text.

  6. Click Authenticate in Slack.

    Clicking Authenticate in Slack initiates a standard Slack OAuth 2.0 authorization flow. Your browser redirects to the Slack workspace where you are currently authenticated or to your default workspace. Slack determines the redirect target based on your active browser session, not Instana. If you are logged in to multiple workspaces, Slack might prompt you to select one.

  7. Select a Slack workspace and authorize the application with the necessary permissions.

    Figure 2. Slack App OAuth
    Slack App OAuth
Note: If you select a private Slack channel, first install the IBM Instana app at workspace level by using any public Slack channel. Then, complete the steps in Using the Slack application with a private channel.
Figure 3. Channel selection
Channel selection

You can find your alert channel in the Alert channels section in the Instana UI.

Note: You need to reauthenticate the alert channel with Slack if you edit an alert channel after it is created.

Slack workspace admin approval

Edit online

If your Slack workspace restricts third-party app installations, a workspace admin must approve the IBM Instana app before installation.

Depending on your organization's Slack workspace configuration, a Slack workspace admin might need to approve the IBM Instana app before it can be installed. If your workspace restricts third-party app installations, the OAuth consent screen displays a Request to Install option instead of Allow. In this case, complete the following steps:

  1. Click Request to Install to submit an approval request to your Slack workspace admin.
  2. The Slack workspace admin receives the request and can review and approve it from Slack Administration > Manage Apps > App Approval Requests.
  3. After the admin approves the request, return to the Instana UI and complete the authentication flow. You might need to redo the alert channel creation steps from the beginning because the original session might have expired during the approval process.
Note: These approval workflows are managed by your organization's Slack administration team and might vary based on your organization's security policies and protocols.
  1. After authentication, enter the Slack channel name to receive alerts.
  2. Click Save.
    Figure 4. Channel selection

    You can find your alert channel in the Alert channels section in the Instana UI.

Note: If you select a private Slack channel, you must first install the IBM Instana app at the workspace level by using a public Slack channel. Then, complete the steps in Using the Slack application with a private channel.
Note: You need to reauthenticate the alert channel with Slack if you edit an alert channel after it is created.

Required scopes

Edit online

The App for Slack requires the following OAuth scopes:

  • channels:history
  • channels:read
  • chat:write
  • groups:history
  • groups:read
  • users:read

Adding IBM Instana app to the Slack channel integrations

Edit online
Note: You need to perform this integration for both public and private channels in Slack.

  1. Click the channel name in the conversation area. A dialog appears with the channel information.

  2. In the channel details panel, select the Integrations tab.

  3. On the Integrations tab, click Add apps.

  4. Search and select IBM Instana.

    Figure 5. Adding App for Slack
    Adding App for Slack

Using the Slack application with a private channel

Edit online

Complete the following steps to use the IBM Instana app within a private Slack channel:

  1. Before you begin, install the IBM Instana app in a public Slack channel.
  2. In Slack, open your private channel and click its name in the conversation area.
  3. In the channel details dialog, select the **Integrations** tab.
  4. Click Add apps.
  5. Search and select IBM Instana. For more information, see Adding the IBM Instana app to the Slack channel integrations.
  6. After adding the app, create your App for Slack alert channel in the Instana by following the steps that are described in Creating an App for Slack alert channel.

Configure alerts in the Instana UI

Edit online

You can configure your existing or new alerts with the App for Slack alert channel. For more information, see Configuring and managing alerts. All alert events automatically appear in your selected Slack channel.

Synchronization of Slack and Instana messages

Edit online

Messages are synchronized between Instana and Slack. Messages that are added within an incident in a Slack thread appear in the Summary and notes with AI section in the Instana UI. Similarly, notes that are added in the Summary and notes with AI section of Instana UI appear in the related Slack incident thread.

Figure 6. Instana notes
Instana notes
Figure 7. Slack thread
Slack thread

In additional, the summary of incident and summary of notes that are generated in the Summary and notes with AI section of the Instana UI also appear in the related Slack incident thread.

Figure 8. Instana incident summary
Instana incident summary
Figure 9. Slack thread summary
Slack thread summary
Note: Currently, this message synchronization feature between Slack and Instana is only applicable for Instana incidents.

Closing event from Slack

Edit online

To close an incident, issue, or change from the Slack application, complete the following steps.

  1. Select an open incident, issue, or change in Slack.

  2. Click Close incident, Close issue, or Close Monitoring issues depending on your event type.
    Figure 10. Closing an event
    Closing an event
  3. Enter a reason for closure, then click Ok.
    Figure 11. Close confirmation
    Close confirmation

  4. The event status in the Instana UI must be updated to manually closed.

    Figure 12. Closed event
    Closed event

  5. In Slack, the event must be updated to Closed, and the app then sends a closure thread reply under the event message for both manual close and auto close events.

    Figure 13. Manual closed event
    Manual closed event
    Figure 14. Auto closed event
    Auto closed event

Troubleshooting

Edit online

Common issues and solutions for integrating IBM Instana with Slack.

OAuth redirect goes to an unexpected Slack workspace

When you click Authenticate in Slack, Slack redirects to the workspace that is associated with your current browser session. If you are redirected to the wrong workspace, complete the following steps:

  1. Log out of that workspace in your browser.
  2. Log in to the intended workspace.
  3. Retry authentication from the Instana UI.

Slack admin approval is required

If your organization's Slack workspace restricts third-party app installations, you see a Request to Install button instead of Allow during OAuth. Complete the following steps:

  1. Submit the request.
  2. Coordinate with your Slack workspace admin to approve the request.

For more information, see Slack workspace admin approval.

IBM Instana app is not found in the Slack Marketplace

The IBM Instana app for Slack is currently undergoing Slack Marketplace certification and is not yet publicly listed. The app is installed through the Instana UI authentication flow, not through the Slack Marketplace.

To install the app, follow the steps in Creating an app for Slack alert channel.

Privacy policy

Edit online

The privacy policy outlines the types of data that is collected and their purposes.

Data collection practices

Edit online

When you install and use the IBM Instana App for Slack, the following types of information are collected:

  • Slack Workspace Information: Team name, team ID, and channel details to enable posting of notifications and interactions.
  • User Information: Slack usernames to generate actions and maintain notes of interactions.
  • Message Content: Limited content of messages or events that you explicitly interact with or authorize the application to access to alert or provide interactive functionality.

For more information, see IBM data retention policy.

Note: Data retention regarding the management and storage of third-party data complies with established policies of IBM.

Usage of your information

Edit online

The collected details are used to:

  • Provide, maintain, and improve integration features.
  • Deliver relevant notifications and updates to your Slack channels as per the configuration.
  • Support troubleshooting, debugging, and technical assistance upon request.
  • Comply with applicable laws and regulations.

For more information, see IBM Terms and Privacy.

Requesting data deletion

Edit online

You can request deletion of your personal data that is collected through the IBM Instana App for Slack.

To request deletion of your data, complete the following steps:

  1. Go to IBM Instana support.
  2. Submit a support ticket requesting removal of your personal data.
  3. Provide any relevant workspace identifiers (such as Slack team ID or channel ID) to help IBM process your request.

IBM reviews and processes data-deletion requests in accordance with its data-protection, privacy, and retention policies.