incident.io

Integrating OpsLevel and incident.io makes it easy for anyone in your engineering organization to see real-time service status alongside the complete context of your service catalog.

SREs, platform engineering, or engineering management can use OpsLevel to ensure incident.io is deployed to all the appropriate services across your architecture.

You can also use incident.io Alert Sources to Detect Services not already present in your software catalog.

How it Works

OpsLevel’s incident.io integration listens for any status changes in your associated incident.io services. When initially configured, it automatically maps any OpsLevel services (generated using the incident.io OpsLevel integration) and creates service suggestions for any items not automatically mapped.

Status Levels

The relationship between incident.io incidents and linked alert sources on OpsLevel services follows the below pattern:

incident.io Usage Checks

For guidance on setting up a tool usage check to verify incident.io is used on all services in your catalog, read more on Service Maturity and check types here.

Requirements

1. API Key

Configuring the incident.io Integration in OpsLevel requires an incident.io API key. When creating the API key from incident.io, the following permissions must be enabled on the API key:

Additionally, the user setting up the integration will require sufficient permissions - usually the Admin role - in incident.io to be able to set up webhooks to send realtime updates about incidents to OpsLevel.

2. Custom Field and Catalog Type setup

For OpsLevel to know which of the services in OpsLevel is impacted by any given incident.io incident, there needs to be a custom field set up on the incident.io side that captures this information. For example, one could set up an "Affected Services" custom field in incident.io which is automatically and/or manually populated with information about which service is affected by an incident. The "Affected Services" custom field would have to be linked to an incident.io catalog type that represents an OpsLevel service. If OpsLevel is integrated into incident.io already, that catalog type can be the "OpsLevel Service" catalog type that is introduced by that integration.

Support

OpsLevel support is available at [email protected] or via your shared OpsLevel Slack channel.

Installation

📘

Integrating both ways

NOTE: For the most ideal setup, integrate OpsLevel into incident.io first, then integrate incident.io into OpsLevel after configuring custom fields. Integrating OpsLevel into incident.io first allows access to the full catalog of OpsLevel services within incident.io, making it very easy to link incidents to the service(s) they impact, which is information that OpsLevel can then in turn ingest to keep service health status up-to-date.

Installing the incident.io integration can be completed in seconds.

1. In the OpsLevel app, from the left-hand menu, navigate to Integrations and click the New Integration tile.
2. Click the incident.io tile and then enter your incident.io API key. Note: If your API key does not have sufficient permissions (see Requirements above), the installation will fail and you will not be able to proceed to the next step.

The installation process fetches custom fields and catalog types from the incident.io account and will attempt an intelligent guess which of the custom fields most likely captures the information about the OpsLevel service impacted by an incident. It prioritizes linking the "OpsLevel Service" custom field generated by the OpsLevel integration on incident.io's side, followed by any custom fields that have the word "Service" in it or are at least categorized under "services" on incident.io's side.

You will be able to change the mapped custom field in the post-installation page showing the integration details.

There will also be a detailed getting started guide to configure webhook delivery from incident.io to OpsLevel.

How to attach an incident.io catalog entry to a service in OpsLevel

There are two ways to attach an incident.io catalog entry to an OpsLevel service. Automatic and Manual

Automatic attachment

An incident.io catalog entry will be automatically linked to an OpsLevel service if the names match exactly, or any given aliases of the catalog entry match any of the aliases of the service. All incident.io catalog entries allow aliases to be set on them - you can do this by editing the catalog entry in incident.io.

Manual attachment

First, navigate to the Operations tab of an OpsLevel service.

1. As shown in the screenshot below, Select Add Alert Sources
2. In the drop-down menu, find and select the correct incident.io catalog entry (you can type its name to search)
3. Click the Add Alert Sources button on the dialog box to save your selection(s)

Detecting Services using incident.io Alert Sources

When an incident.io catalog entry is synced to OpsLevel, we can create a service suggestion if there is no OpsLevel service with an alias that matches the incident.io catalog entry's name. Service suggestions are found in the Service Detection page, for more information on how to interact with these suggestions check out this guide. To receive suggested services, ensure that your incident.io integration has Service Detection enabled.

If an incident.io catalog entry contributes to a detected service, when the service is accepted it will include: a link to the Alert Source on the Operations tab.