Opsgenie

CatalogScorecardsTeams

Opsgenie is an alert and on-call management platform from Atlassian. By integrating Opsgenie with Cortex, you can manage on-call for your entities, drive insights into your on-call rotations and escalation policies, and view alerts with greater context in the event timeline.

Setup and configuration

Getting started

In order to connect Cortex to your Opsgenie instance, you’ll need to create an Opsgenie API key.

The key should have the following permissions:

• Read
• Configuration Access

Configuration

Once you've generated the API key, you can configure the integration in Opsgenie settings in Cortex.

caution

If you do not see the settings page you're looking for, you likely don't have the proper permissions and need to contact your admin.

Enter the following information in settings:

• Subdomain: Subdomain assigned to your Opsgenie instance.
• API key: API key generated in Opsgenie.
• Use European service region (optional): Enables the EU region of Opsgenie when toggled on.

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

Registration

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*).

Schedules

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

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.

All ownership details

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

• Ownership

  • All owners
  • Teams

• Team

  • Description
  • ID
  • Identity provider groups
  • Is archived
  • Is fallback
  • Is inherited
  • Members
  • Tag

• Team members

  • Description
  • Email
  • Has Cortex user
  • Identity provider sources
  • Name
  • Notifications enabled
  • Roles

• Team member role

  • Tag
  • Type

• Identity provider group

  • Group identifier
  • Source

  Definition: ownership

Example

Because ownership is a key part of using Cortex, a rule that confirms ownership is set belongs in the first level of an entity onboarding or production readiness Scorecard:

ownership != null

All owner details

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

• Team member

  • Description
  • Email
  • Has Cortex user
  • Identity provider sources
  • Name
  • Notifications enabled
  • Roles

• Team member role

  • Tag
  • Type

• Identity provider group

  • Group identifier
  • Source

  Definition: ownership.allOwners()

Example

To make sure that entity owners have an email address set, you can use this expression to write a Scorecard rule:

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

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.

Team details

List of teams for each entity.

Definition: ownership.teams()

Example

For a Scorecard focused on best practices, you could use this rule to make sure teams follow naming conventions:

ownership.teams().any(team => team.tag.matchesIn("[Ee]xample"))

Entities will pass this rule if they have an associated team with a tag containing "Example" or "example."

You can also use this expression to query by team ID for all entities owned by a specific team:

ownership.teams().any(team => team.id == "Cortex-Engineering")

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.

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.