All jobs

Add CloudWatch Alarms to a Serverless Framework Service

Yes. An agent adds error, throttle and duration alarms with an SNS topic to your Serverless Framework service, verifies the generated CloudFormation and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the service as the framework deploys it. In a service shaped like the aws-node-express-dynamodb-api example in serverless/examples, serverless.yml declares frameworkVersion: "4", one function api with handler handler.handler on an httpApi: "*" event, a nodejs24.x arm64 provider, an IAM statement for the UsersTable DynamoDB table and the table itself under resources. handler.js is an Express app behind serverless-http with GET /users/:userId and POST /users, and its error path logs and answers 500. There is no plugins section, no AWS::CloudWatch::Alarm and no SNS topic, so a burst of 500s or a throttled function would be visible only to someone reading the Lambda console.

It chooses the smallest configuration that produces real alarms. serverless-plugin-aws-alerts is added under plugins and configured in custom.alerts: a topics block with one alarm topic named from the service and stage, with an email notifications subscription whose address comes from a ${param:alertEmail} so nothing personal is in the file; and an alarms list of functionErrors, functionThrottles and functionDuration. The plugin's defaults for those three, a sum of errors at or above one in a sixty-second period, the same for throttles, and an average duration at or above five hundred milliseconds, are written down in the description with a sentence on each, because the duration threshold is the one a team usually tunes. The definitions block overrides functionDuration with a threshold tied to the function's timeout rather than the default, and treatMissingData is set to notBreaching on the error alarm so a quiet night does not page.

The alarms are proven without deploying. Serverless Framework v4 signs in before any command, so the run is started in a Project that holds SERVERLESS_ACCESS_KEY as a secret, with POST /o/{org}/p/{project}/sessions and the same body, and the sandbox reads it as an environment variable. The agent runs serverless package and reads the generated .serverless/cloudformation-template-update-stack.json, confirming three AWS::CloudWatch::Alarm resources whose Dimensions name the api function, one AWS::SNS::Topic, and the subscription, and that the DynamoDB table and IAM role are unchanged. It then runs serverless print to show the resolved configuration with the parameter substituted, and keeps both outputs for the pull request.

The repository's own checks run too. The examples repository validates each example's README front matter with node validate.js and regenerates the index with npm run check-docs, so the agent updates the README with an Alarms section that explains the three alarms and the parameter, and runs both scripts. For a single-service repository the same step is the service's own lint and test commands, which the agent reads from package.json.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add CloudWatch alarms to this Serverless Framework service. Read serverless.yml, handler.js, package.json and README.md first, and if the repository holds several services, read validate.js and the root package.json too. Add serverless-plugin-aws-alerts under plugins and configure custom.alerts with one SNS alarm topic named from the service and stage, an email subscription whose address comes from a stage parameter rather than a literal, and the functionErrors, functionThrottles and functionDuration alarms. Override functionDuration with a threshold derived from the function's timeout and set treatMissingData to notBreaching on functionErrors. Using the SERVERLESS_ACCESS_KEY from the environment, run serverless package and inspect .serverless/cloudformation-template-update-stack.json: confirm three AWS::CloudWatch::Alarm resources with Dimensions naming the function, one AWS::SNS::Topic and its subscription, and no change to the existing table or role. Run serverless print to show the resolved configuration. Add an Alarms section to the README and run the repository's validation scripts. Open a pull request that quotes the alarm resources from the template and the print output; do not deploy.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that adds a plugins section and a custom.alerts block to serverless.yml, adds the plugin to package.json, and adds an Alarms section to README.md. handler.js does not change, and the resources block with the DynamoDB table does not change; the description says so before anything else, because a reviewer of an infrastructure diff wants to know the data store is untouched.

The description quotes the three AWS::CloudWatch::Alarm resources and the AWS::SNS::Topic from the packaged template, with the MetricName, Threshold, Period and Dimensions of each, and the serverless print output showing the email parameter resolved for the stage. It lists each default the plugin applied and the one it overrode, and says plainly that nothing was deployed.

Before merging, a reviewer sets the alertEmail parameter for each stage, decides whether the duration threshold should be a fraction of the timeout or an absolute number, and whether a second topic for ok notifications is wanted. A follow-up on the same session can add a dashboard, which the same plugin generates, without starting over.

Run it on every service without alarms

This is a change you want on every service, done the same way: a POST /o/{org}/p/{project}/sessions with this prompt and one repository in resources for each service, sent from the terminal to the Project that holds the access key, one run per repository. Each run reads that service's own functions and timeouts, packages it with the access key from that Project's secrets, and opens its own pull request. The sandbox parks with its disk when the turn ends, so a follow-up such as add functionInvocations with a threshold for the checkout function only wakes it with the plugin installed and the template already packaged.

With a webhook URL on the API key, Rush posts run.completed or run.failed with the session_url for each run, so the pull request links collect in one place as the runs finish.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Alarm configuration is only as good as the CloudFormation it produces, and the way to see that without touching an AWS account is to package the service and read the template. The agent does that in its own sandbox with the service's access key held as a Project secret, and the template, the resolved configuration and the validation scripts' output are all in the run's record.

The record also shows the choices. The transcript has the agent reading the function's timeout before setting the duration threshold, choosing a stage parameter over a literal email address, and confirming the table and role resources are byte-for-byte unchanged in the template. A reviewer who wants different thresholds can say so in a follow-up and the parked sandbox repackages with the change.

Frequently asked questions

Does the run deploy anything to AWS?

No. It runs serverless package and serverless print, which produce the CloudFormation template and the resolved configuration locally, and the prompt says not to deploy. Deployment happens through the team's usual pipeline after the pull request merges.

Why does it need a Serverless access key?

Because Serverless Framework v4 requires authentication before it runs commands, including package. The key is saved once as a Project secret, and a run started in that Project reads it as the SERVERLESS_ACCESS_KEY environment variable; it is never written into the repository or the pull request.

Where does the alert email address go?

Into a stage parameter the configuration reads with ${param:alertEmail}, set per stage in the dashboard or the stages block, so the file holds no address. The README section names the parameter and the pull request shows serverless print resolving it.

What are the default thresholds?

The plugin's functionErrors and functionThrottles alarms fire on a sum of one or more in a sixty-second period, and functionDuration on an average of five hundred milliseconds. The pull request overrides the duration threshold to follow the function's timeout and lists each default it kept.

Can alarms differ per function?

Yes. A function's own alarms list merges with the global one, so one function can raise a threshold, add functionInvocations or disable an alarm with enabled: false. The first pass applies the three alarms globally because the example has one function.

More Serverless Framework jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading