Opsgenie

CatalogScorecardsTeams

warning

Atlassian is deprecating the Opsgenie product and encouraging their customers to migrate to Jira Service Management. Read more about moving from Opsgenie to Jira Service Management on Atlassian's web site.

Cortex is actively working on developing an integration with Jira Service Management.

Opsgenie is an alert and on-call management platform from Atlassian.

Integrating Opsgenie with Cortex allows you to:

• Pull in on-call rotation data and escalation policies
  • The on-call user or team will appear in the Current On-call block on an entity's details page.
  • You can also view on-call information on an entity page in its side panel under Integrations > On-call.
• View alerts from Opsgenie in an entity's event timeline
• Create Scorecards that track progress and drive alignment on projects involving your on-call schedules and alerts

How to configure Opsgenie with Cortex

Prerequisite

Before getting started, create an Opsgenie API key with the following permissions:

• Read
• Configuration Access

Configure the integration in Cortex

1. In Cortex, navigate to the Opsgenie settings page:
   1. In Cortex, click your avatar in the lower left corner, then click Settings.
   2. Under "Integrations", click Opsgenie.
2. Configure the Opsgenie integration form:
   • Subdomain: Enter the subdomain assigned to your Opsgenie instance.
   • API key: Enter your Opsgenie API key.
   • Use European service region: Optionally, toggle this setting on to enable the EU region of Opsgenie.
3. Click Save.

If you’ve set everything up correctly, you’ll see the option to Remove Integration in settings.

You can also use the Test configuration button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

How to connect Cortex entities to Opsgenie

Discovery

By default, Cortex will use the entity tag (e.g. my-entity) as the "best guess" value for the backend and service tags on your alerts. For example, if your alert in Opsgenie has the tag backend:my-entity, the alert will be automatically associated with the entity in Cortex with a unique identifier of my-entity.

If your Opsgenie tags don’t cleanly match the Cortex entity tag, or you use different identifying tags, you can override this in the Cortex entity descriptor.

Entity descriptor

If you need to override automatic discovery, you can define the following block in your Cortex entity descriptor.

x-cortex-alerts:
  - type: opsgenie
    tag: different-tag
    value: my-entity-override-tag

Field	Description	Required
type	Type of alert (in this case, opsgenie)	✓
tag	Type of tag in Opsgenie (e.g. backend)	✓
value	Alert in Opsgenie (e.g. my-entity-override-tag)	✓

For example, for the tag different-tag:my-entity-override-tag, the entity descriptor would have different-tag in the tag field and my-entity-override-tag in the value field.

You can add a list of tags to use for lookup. Cortex will use an OR operator when querying Opsgenie (e.g. backend:my-entity OR service:another-value).

The value field also supports wildcards (e.g. value: my-entity*).

Adding a schedule

You can define the following block in an entity descriptor to add an Opsgenie schedule. Cortex supports adding a schedule by ID or UUID. You can add one schedule per entity.

The UUID for the schedule can be found in URL when viewing schedule details by clicking on the schedule name under who is on-call.

x-cortex-oncall:
  opsgenie:
    type: SCHEDULE
    id: Cortex-Engineering

Field	Description	Required
type	Opsgenie component being added (in this case, SCHEDULE)	✓
id	Schedule ID or UUID	✓

Ownership

You can define the following block in your Cortex entity descriptor to add your Opsgenie group as an owner.

x-cortex-owners:
  - type: group
    name: My Opsgenie Team
    provider: OPSGENIE
    description: This is a description for this owner

Field	Description	Required
type	Ownership type (in this case, group)	✓
name	Name of the team defined in Opsgenie (**case-sensitive)	✓
provider	Identity provider (in this case, OPSGENIE)	✓
description	Description for the team, to be displayed in Cortex

Identity mappings

Cortex maps email addresses in your Opsgenie instance to email addresses that belong to team members in Cortex. When identity mapping is set up, users will be able to see their personal on-call status from the developer homepage.

Expected results

Entity pages

Once the Opsgenie integration is set up, current on-call information from Opsgenie will display in the on-call block on an entity's details page.

Integrations - On-call

Data from the Opsgenie integration will also appear on the On-call page under the Integrations tab.

The associated Opsgenie escalation policy will by hyperlinked in the Escalation Policy block at the top of the page.

Under the Escalations section, you'll find each level associated with the policy. Owners assigned to each level will also be hyperlinked to the user or team page in Opsgenie.

Scorecards and CQL

With the Opsgenie integration, you can create Scorecard rules and write CQL queries based on Opsgenie on-call schedules and alerts.

See more examples in the CQL Explorer in Cortex.

Check if on-call is set

Check if entity has a registered schedule.

Definition: oncall (==/!=) null

Example

For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:

oncall != null

This rule will pass if an entity has an on-call schedule set.

Number of alerts

Number of alerts for a given lookback period that match a given search query.

Definition: oncall.numOfAlerts(lookback=<duration>,query=<query>).length

Example

For a Scorecard focused on maturity or quality, you can use this expression to make sure a given entity has fewer than two alerts in the last month:

oncall.numOfAlerts(lookback=duration("P1M"),query="status: open").length < 2

You could also refine this rule by specifying priority level:

oncall.numOfAlerts(lookback=duration("P1M"),query="priority: P1").length < 2

Entities will pass this rule if they have fewer than 2 alerts with priority level "P1" in the last month.

Number of escalations

Number of escalation tiers in escalation policy.

Definition: oncall.numOfEscalations()

Details

Example

This expression could be used in a Scorecard focused on production readiness or service maturity. For example, you can check that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup:

oncall.numOfEscalations() >= 2

While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.

On-call metadata

On-call metadata.

• ID

• Name

• Type

  Definition: oncall.details()

Example

To find all entities without a schedule-type on-call registration, you can use this expression in the Query builder:

oncall.details().type =! "schedule"

If you're migrating on-call policies, you could use this rule to check for outdated policies. Let's say, for example, all outdated Opsgenie policies start with "Legacy" in their titles.

oncall.details().id.matches("Legacy*") == false

Entities with on-call policies that start with "Legacy" will fail, while those with other policy names will pass.

Ownership CQL

All ownership details

A special built-in type that supports a null check or a count check, used to enforce ownership of entities.

Definition: ownership: Ownership | Null

Example

An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:

ownership.teams().length > 0

All owner details

List of owners, including team members and individual users, for each entity

Definition: ownership.allOwners()

Example

The Scorecard might include a rule to ensure that entity owners all have an email set:

ownership.allOwners().all((member) => member.email != null)

Team details

List of teams for each entity

Definition: ownership.teams(): List<Team>

Example

The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:

ownership.teams().all(team => team.description != null and team.isArchived == false)

Dev homepage

The Opsgenie integration enables Cortex to pull on-call information into the on-call block on the Dev homepage. On-call data from Opsgenie is refreshed every 1 minute.

Background sync

Cortex conducts an ownership sync for Opsgenie teams every day at 9 a.m. UTC.

Still need help?

The following are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:

• Email: help@cortex.io, or open a support ticket in the in app Resource Center
• Chat: Available in the Resource Center
• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your customer success manager.