About this page. Adapted from documentation I wrote for a government platform. Platform and team names, infrastructure details, repository names and internal references have been removed or replaced. The structure, the writing and the approach are as I wrote them.

Alerts tell your on-call engineer that something is wrong before a user reports it. You define them in code and they are reviewed through pull requests.

Before you start

You need:

• an approved alerting account for your team
• your team added to the alert configuration repository
• agreement in your team on what is worth waking someone up for

Pull the latest changes:

git checkout main && git pull

Add your alert configuration

1. Create a branch in the alert configuration repository.
2. Add a Scala file named after your service in the service configuration folder:
   terminalCopy

   src/main/scala/com/example/platform/alerting/configs

3. Create an object that extends AlertConfig:
   terminalCopy

   object <MyService> extends AlertConfig {
     override val alertConfig: Seq[AlertConfigBuilder] = teamAlerts(Seq(
       "<service-name>"
     )).withIntegrations(<MyService>Integration)
   }

   Replace <MyService> with your service in upper camel case, and <service-name> with its name in lower case with hyphens.

4. Set the thresholds for the conditions you want to alert on.

Ask your reviewer to check the thresholds specifically. An alert that fires constantly gets muted, and a muted alert is worse than no alert.

Merge and deploy

Raise a pull request and ask a teammate to review it. Once merged, the pipeline generates your alerts and deploys them to every environment. Your alerts become active about 30 minutes after the pipeline finishes.

Check it worked

1. In the platform catalogue, open your service and check its commissioning state shows alerting as configured.
2. Open your team's alerting configuration and confirm your alerts are listed and active.

If they are not showing 30 minutes after the pipeline finished, ask in your platform support channel.