Skip to main content

Soundcheck PageDuty Integration

Spotify Plugins for Backstage: Soundcheck - PagerDuty Integration​

PagerDuty integration plugin for Soundcheck.

PagerDuty integration plugin supports the extraction of the following facts:

Prerequisites​

Configure PagerDuty integration in Backstage​

Integrations are configured at the root level of app-config.yaml, here's an example configuration for PagerDuty:

soundcheck:
  collectors:
    pagerduty:
      token: ${PAGERDUTY_TOKEN}
      server: api.pagerduty.com

Add the PagerDutyFactCollector to Soundcheck​

First, add the @spotify/backstage-plugin-soundcheck-backend-module-pagerduty package:

yarn workspace backend add @spotify/backstage-plugin-soundcheck-backend-module-pagerduty

Then in packages/backend/src/plugins/soundcheck.ts, add the PagerDutyFactCollector:

import { SoundcheckBuilder } from '@spotify/backstage-plugin-soundcheck-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
+ import { PagerDutyFactCollector } from '@spotify/backstage-plugin-soundcheck-backend-module-pagerduty';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  return SoundcheckBuilder.create({ ...env })
    .addFactCollectors(
+      PagerDutyFactCollector.create({
+        config: env.config,
+        cache: env.cache,
+        logger: env.logger,
+      }),
    )
    .build();
}

New Backend System​

If you are using the New Backend System, instead of the above, you can just add the following to your packages/backend/src/index.ts file:

const backend = createBackend();

backend.add(import('@spotify/backstage-plugin-soundcheck-backend'));
+ backend.add(import('@spotify/backstage-plugin-soundcheck-backend-module-pagerduty'));
// ...

backend.start();

See the the soundcheck-backend documentation for additional details on creating the Soundcheck backend.

Rate Limiting (Optional)​

This fact collector can be rate limited in Soundcheck using the following configuration:

soundcheck:
  job:
    workers:
      pagerduty:
        limiter:
          max: 400
          duration: 60000

PageDuty API has a limit of 960 requests per minute. We recommend setting your rate limit to something below this, i.e. in the example above, we set the rate limit to 400 executions every minute.

This fact collector handles 429 rate limit errors from PageDuty. Soundcheck will automatically wait and retry requests that are rate limited.

Plugin Configuration​

Collection of facts is driven by config. To learn more about the config, see the Defining PagerDuty Fact Collectors.

  1. Create pagerduty-facts-collectors.yaml in the root of your Backstage repository and fill in all your PagerDuty fact collectors. A simple example PagerDuty fact collector is listed below.

    Note: this file will be loaded at runtime along with the rest of your Backstage configuration files, so make sure it's available in deployed environments in the same way as your app-config.yaml files.

    ---
    token: dummy
    server: api.pagerduty.com
    collects:
      - type: Standards
        filter:
          - spec.lifecycle: 'production'
            spec.type: 'website'
        cache: false

  2. Add a soundcheck collectors field to app-config.yaml and reference the newly created pagerduty-facts-collectors.yaml

    # app-config.yaml
    soundcheck:
      collectors:
        pagerduty:
          $include: ./pagerduty-facts-collectors.yaml

Defining PagerDuty Fact Collectors​

This section describes the data shape and semantics of PagerDuty Fact Collectors.

Overall Shape Of A PagerDuty Fact Collector​

The following is an example of a descriptor file for a PagerDuty Fact Collector:

---
frequency:
  cron: '0 * * * *'
filter:
  kind: 'Component'
cache:
  duration:
    hours: 2
collects:
  - type: Service
    filter:
      - spec.lifecycle: 'production'
        spec.type: 'website'
    cache: false

See below for details about these fields.

frequency [optional]​

The frequency at which the collector should be executed. Possible values are either a cron expression { cron: ... } or HumanDuration. This is the default frequency for each extractor.

filter [optional]​

A filter specifying which entities to collect the specified facts for. Matches the filter format used by the Catalog API. This is the default filter for each extractor.

cache [optional]​

If the collected facts should be cached, and if so for how long. Possible values are either true or false or a nested { duration: HumanDuration } field. This is the default cache config for each extractor.

collects [required]​

An array describing which facts to collect and how to extract them. See below for details about the overall shape of a fact extractor.

Overall Shape Of A Fact Extractor​

Each extractor supports the fields described below.

type [required]​

The type of the extractor (e.g. Service, Standards).

frequency [optional]​

The frequency at which the fact extraction should be executed. Possible values are either a cron expression { cron: ... } or HumanDuration. If provided it overrides the default frequency provided at the top level. If not provided it defaults to the frequency provided at the top level. If neither extractor's frequency nor default frequency is provided the fact will only be collected on demand. Example:

frequency:
  minutes: 10

filter [optional]​

A filter specifying which entities to collect the specified facts for. Matches the filter format used by the Catalog API. If provided it overrides the default filter provided at the top level. If not provided it defaults to the filter provided at the top level. If neither extractor's filter nor default filter is provided the fact will be collected for all entities.

cache [optional]​

If the collected facts should be cached, and if so for how long. Possible values are either true or false or a nested { duration: HumanDuration } field. If provided it overrides the default cache config provided at the top level. If not provided it defaults to the cache config provided at the top level. If neither extractor's cache nor default cache config is provided the fact will not be cached. Example:

cache:
  duration:
    hours: 24

Entity configuration​

In your catalog-info.yaml add following metadata annotation to allow the plugin to map entity to a service in PagerDuty.

metadata:
  annotations:
    pagerduty.com/service-id: pd-test-service-id

Alternatively you can also configure integration key.

metadata:
  annotations:
    pagerduty.com/integration-key: pd-test-integration-key

Collecting Service Fact​

Service fact contains information about a service from PagerDuty Service API.

Shape of A Service Fact Collector​

The shape of a Service Fact Collector matches the Overall Shape Of A PagerDuty Fact Collector (restriction: type: Service).

The following is an example of the Service Fact Collector config:

- type: Service
  cache: true
  frequency:
    cron: '0 * * * *'

Shape of A Service Fact Check​

The shape of a Service Fact Check matches the Shape of a Fact Check.

The following is an example of the Service fact checks:

soundcheck:
  checks:
    - id: requires_type_to_be_service
      rule:
        factRef: pagerduty:default/service
        path: $.type
        operator: equal
        value: service

Collecting Standards Fact​

Standards fact contains information about standards from PagerDuty Standards API.

Shape of A Standards Fact Collector​

The shape of a Standards Fact Collector matches the Overall Shape Of A PagerDuty Fact Collector (restriction: type: Standards).

The following is an example of the Standards Fact Collector config:

- type: Standards
  cache: true
  frequency:
    cron: '0 * * * *'

Shape of A Standards Fact​

The shape of a Standards Fact is based on the Fact Schema.

For a description of the data collected regarding branch protection, refer to the PagerDuty API documentation.

Shape of A Standards Fact Check​

The shape of a Standards Fact Check matches the Shape of a Fact Check.

The following is an example of the Standards fact checks:

soundcheck:
  checks:
    - id: requires_resource_type_to_be_technical_service
      rule:
        factRef: pagerduty:default/standards
        path: $.resource_type
        operator: equal
        value: technical_service