{"id":13527800,"url":"https://github.com/ACloudGuru/serverless-plugin-aws-alerts","last_synced_at":"2025-04-01T10:30:31.867Z","repository":{"id":38898810,"uuid":"73655892","full_name":"ACloudGuru/serverless-plugin-aws-alerts","owner":"ACloudGuru","description":"A Serverless Framework plugin that creates CloudWatch alarms for functions.","archived":true,"fork":false,"pushed_at":"2023-09-05T19:44:34.000Z","size":1255,"stargazers_count":531,"open_issues_count":66,"forks_count":150,"subscribers_count":69,"default_branch":"master","last_synced_at":"2024-10-27T06:23:17.100Z","etag":null,"topics":["aws","aws-cloudwatch","serverless","serverless-framework"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ACloudGuru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-11-14T01:35:45.000Z","updated_at":"2024-09-05T12:40:32.000Z","dependencies_parsed_at":"2024-01-13T16:23:09.310Z","dependency_job_id":"687c523a-2a8d-43f8-9edd-fd7bec94743a","html_url":"https://github.com/ACloudGuru/serverless-plugin-aws-alerts","commit_stats":{"total_commits":139,"total_committers":45,"mean_commits":3.088888888888889,"dds":0.7553956834532374,"last_synced_commit":"7f1b414ca037908003850504cb1e3bffc137a57d"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ACloudGuru%2Fserverless-plugin-aws-alerts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ACloudGuru%2Fserverless-plugin-aws-alerts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ACloudGuru%2Fserverless-plugin-aws-alerts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ACloudGuru%2Fserverless-plugin-aws-alerts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ACloudGuru","download_url":"https://codeload.github.com/ACloudGuru/serverless-plugin-aws-alerts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222715679,"owners_count":17027699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-cloudwatch","serverless","serverless-framework"],"created_at":"2024-08-01T06:02:02.256Z","updated_at":"2024-11-02T12:32:30.774Z","avatar_url":"https://github.com/ACloudGuru.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Serverless AWS Alerts Plugin\n  [![NPM version][npm-image]][npm-url]\n  [![Build Status][travis-image]][travis-url]\n  [![Dependency Status][daviddm-image]][daviddm-url]\n  [![codecov][codecov-image]][codecov-url]\n\nA Serverless plugin to easily add CloudWatch alarms to functions\n\n## Installation\n```bash\nnpm i serverless-plugin-aws-alerts --save-dev\n\nOR\n\nyarn add --dev serverless-plugin-aws-alerts\n```\n\n## Usage\n\n### Basic Usage\n```yaml\n# serverless.yml\n\nplugins:\n  - serverless-plugin-aws-alerts\n\ncustom:\n  alerts:\n    stages:\n      - production\n    topics:\n      alarm:\n        topic: ${self:service}-${opt:stage}-alerts-alarm\n        notifications:\n          - protocol: email\n            endpoint: name@domain.com # Change this to your email address\n    alarms:\n      - functionErrors\n      - functionThrottles\n```\n\n### Advanced Usage\n```yaml\nservice: your-service\nprovider:\n  name: aws\n  runtime: nodejs12.x\n\nplugins:\n  - serverless-plugin-aws-alerts\n  \ncustom:\n  alerts:\n    stages: # Optionally - select which stages to deploy alarms to\n      - production\n      - staging\n\n    dashboards: true\n\n    nameTemplate: $[functionName]-$[metricName]-Alarm # Optionally - naming template for alarms, can be overwritten in definitions\n    prefixTemplate: $[stackName] # Optionally - override the alarm name prefix\n\n    topics:\n      ok: ${self:service}-${opt:stage}-alerts-ok\n      alarm: ${self:service}-${opt:stage}-alerts-alarm\n      insufficientData: ${self:service}-${opt:stage}-alerts-insufficientData\n    definitions:  # these defaults are merged with your definitions\n      functionErrors:\n        period: 300 # override period\n      customAlarm:\n        actionsEnabled: false # Indicates whether actions should be executed during any changes to the alarm state. The default is TRUE\n        description: 'My custom alarm'\n        namespace: 'AWS/Lambda'\n        nameTemplate: $[functionName]-Duration-IMPORTANT-Alarm # Optionally - naming template for the alarms, overwrites globally defined one\n        prefixTemplate: $[stackName] # Optionally - override the alarm name prefix, overwrites globally defined one\n        metric: duration\n        threshold: 200\n        statistic: Average\n        period: 300\n        evaluationPeriods: 1\n        datapointsToAlarm: 1\n        comparisonOperator: GreaterThanOrEqualToThreshold\n    alarms:\n      - functionThrottles\n      - functionErrors\n      - functionInvocations\n      - functionDuration\n\nfunctions:\n  foo:\n    handler: foo.handler\n    alarms: # merged with function alarms\n      - customAlarm\n      - name: fooAlarm # creates new alarm or overwrites some properties of the alarm (with the same name) from definitions\n        namespace: 'AWS/Lambda'\n        actionsEnabled: false\n        metric: errors # define custom metrics here\n        threshold: 1\n        statistic: Minimum\n        period: 60\n        evaluationPeriods: 1\n        datapointsToAlarm: 1\n        comparisonOperator: GreaterThanOrEqualToThreshold\n```\n\n## Anomaly Detection Alarms\n\nYou can create alarms using [CloudWatch AnomalyDetection](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Anomaly_Detection.html) to alarm when data is outside a number of standard deviations of normal, rather than at a static threshold.\nWhen using anomaly detection alarms the threshold property specifies the \"Anomaly Detection Threshold\" seen in the AWS console.\n\nDefault alarms can also be updated to be anomaly detection alarms by adding the `type: anomalyDetection` property.\n\n```yaml\nfunctions:\n  foo:\n    handler: foo.handler\n    alarms:\n      - name: fooAlarm\n        type: anomalyDetection\n        namespace: 'AWS/Lambda'\n        metric: Invocations\n        threshold: 2\n        statistic: Sum\n        period: 60\n        evaluationPeriods: 1\n        datapointsToAlarm: 1\n        comparisonOperator: LessThanLowerOrGreaterThanUpperThreshold\n  bar:\n    handler: bar.handler\n    alarms:\n      - name: functionErrors\n        threshold: 2\n        type: anomalyDetection\n        comparisonOperator: LessThanLowerOrGreaterThanUpperThreshold\n      - name: functionInvocations\n        threshold: 2\n        type: anomalyDetection\n        comparisonOperator: LessThanLowerOrGreaterThanUpperThreshold\n```\n\n## Multiple topic definitions\n\nYou can define several topics for alarms. For example you want to have topics for critical alarms\nreaching your pagerduty, and different topics for noncritical alarms, which just send you emails.\n\nIn each alarm definition you have to specify which topics you want to use. In following example\nyou get an email for each function error, pagerduty gets alarm only if there are more than 20\nerrors in 60s\n\n```yaml\ncustom:\n  alerts:\n\n    topics:\n      critical:\n        ok:\n          topic: ${self:service}-${opt:stage}-critical-alerts-ok\n          notifications:\n          - protocol: https\n            endpoint: https://events.pagerduty.com/integration/.../enqueue\n        alarm:\n          topic: ${self:service}-${opt:stage}-critical-alerts-alarm\n          notifications:\n          - protocol: https\n            endpoint: https://events.pagerduty.com/integration/.../enqueue\n\n      nonCritical:\n        alarm:\n          topic: ${self:service}-${opt:stage}-nonCritical-alerts-alarm\n          notifications:\n          - protocol: email\n            endpoint: alarms@email.com\n\n    definitions:  # these defaults are merged with your definitions\n      criticalFunctionErrors:\n        namespace: 'AWS/Lambda'\n        metric: Errors\n        threshold: 20\n        statistic: Sum\n        period: 60\n        evaluationPeriods: 10\n        comparisonOperator: GreaterThanOrEqualToThreshold\n        okActions:\n          - critical\n        alarmActions:\n          - critical\n      nonCriticalFunctionErrors:\n        namespace: 'AWS/Lambda'\n        metric: Errors\n        threshold: 1\n        statistic: Sum\n        period: 60\n        evaluationPeriods: 10\n        comparisonOperator: GreaterThanOrEqualToThreshold\n        alarmActions:\n          - nonCritical\n    alarms:\n      - criticalFunctionErrors\n      - nonCriticalFunctionErrors\n\n```\n## SNS Topics\n\nIf topic name is specified, plugin assumes that topic does not exist and will create it. To use existing topics, specify ARNs or use CloudFormation (e.g. Fn::ImportValue, Fn::Join and Ref) to refer to existing topics.\n\n#### ARN support\n\n```yaml\ncustom:\n  alerts:\n    topics:\n      alarm:\n        topic: arn:aws:sns:${self:region}:${self::accountId}:monitoring-${opt:stage}\n```\n\n#### CloudFormation support\n\n```yaml\ncustom:\n  alerts:\n    topics:\n      alarm:\n        topic:\n          Fn::ImportValue: ServiceMonitoring:monitoring-${opt:stage, 'dev'}\n      ok:\n        topic:\n          Fn::Join:\n            - ':'\n            - - arn:aws:sns\n              - Ref: AWS::Region\n              - Ref: AWS::AccountId\n              - example-ok-topic\n      insufficientData:\n        topic:\n          Ref: ExampleInsufficientdataTopic\n\nresources:\n  Resources:\n    ExampleInsufficientdataTopic:\n      Type: AWS::SNS::Topic\n      Properties:\n        DisplayName: example-insufficientdata-topic\n        Subscription:\n          - Endpoint: me@example.com\n            Protocol: EMAIL\n```\n\n## SNS Notifications\n\nYou can configure subscriptions to your SNS topics within your `serverless.yml`. For each subscription, you'll need to specify a `protocol` and an `endpoint`.\n\nThe following example will send email notifications to `me@example.com` for all messages to the Alarm topic:\n\n```yaml\ncustom:\n  alerts:\n    topics:\n      alarm:\n        topic: ${self:service}-${opt:stage}-alerts-alarm\n        notifications:\n          - protocol: email\n            endpoint: me@example.com\n```\n\nYou can configure notifications to send to webhook URLs, to SMS devices, to other Lambda functions, and more. Check out the AWS docs [here](http://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html) for configuration options.\n\n## Metric Log Filters\nYou can monitor a log group for a function for a specific pattern. Do this by adding the pattern key.\nYou can learn about custom patterns at: http://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html\n\nThe following would create a custom metric log filter based alarm named `barExceptions`. Any function that included this alarm would have its logs scanned for the pattern `exception Bar` and if found would trigger an alarm.\n\n```yaml\ncustom:\n  alerts:\n    definitions:\n      barExceptions:\n        metric: barExceptions\n        threshold: 0\n        statistic: Minimum\n        period: 60\n        evaluationPeriods: 1\n        comparisonOperator: GreaterThanThreshold\n        pattern: 'exception Bar'\n      bunyanErrors:\n        metric: bunyanErrors\n        threshold: 0\n        statistic: Sum\n        period: 60\n        evaluationPeriods: 1\n        datapointsToAlarm: 1\n        comparisonOperator: GreaterThanThreshold\n        pattern: '{$.level \u003e 40}'\n```\n\n\u003e Note: For custom log metrics, namespace property will automatically be set to stack name (e.g. `fooservice-dev`).\n\n## Custom Naming\nYou can define custom naming template for the alarms. `nameTemplate` property under `alerts` configures naming template for all the alarms, while placing `nameTemplate` under alarm definition configures (overwrites) it for that specific alarm only. Naming template provides interpolation capabilities, where supported placeholders are:\n  - `$[functionName]` - function name (e.g. `helloWorld`)\n  - `$[functionId]` - function logical id (e.g. `HelloWorldLambdaFunction`)\n  - `$[metricName]` - metric name (e.g. `Duration`)\n  - `$[metricId]` - metric id (e.g. `BunyanErrorsHelloWorldLambdaFunction` for the log based alarms, `$[metricName]` otherwise)\n\n\u003e Note: All the alarm names are prefixed with stack name (e.g. `fooservice-dev`).\n\n## Default Definitions\nThe plugin provides some default definitions that you can simply drop into your application. For example:\n\n```yaml\nalerts:\n  alarms:\n    - functionErrors\n    - functionThrottles\n    - functionInvocations\n    - functionDuration\n```\n\nIf these definitions do not quite suit i.e. the threshold is too high, you can override a setting without\ncreating a completely new definition.\n\n```yaml\nalerts:\n  definitions:  # these defaults are merged with your definitions\n    functionErrors:\n      period: 300 # override period\n      treatMissingData: notBreaching # override treatMissingData\n```\n\nThe default definitions are below.\n\n```yaml\ndefinitions:\n  functionInvocations:\n    namespace: 'AWS/Lambda'\n    metric: Invocations\n    threshold: 100\n    statistic: Sum\n    period: 60\n    evaluationPeriods: 1\n    datapointsToAlarm: 1\n    comparisonOperator: GreaterThanOrEqualToThreshold\n    treatMissingData: missing\n  functionErrors:\n    namespace: 'AWS/Lambda'\n    metric: Errors\n    threshold: 1\n    statistic: Sum\n    period: 60\n    evaluationPeriods: 1\n    datapointsToAlarm: 1\n    comparisonOperator: GreaterThanOrEqualToThreshold\n    treatMissingData: missing\n  functionDuration:\n    namespace: 'AWS/Lambda'\n    metric: Duration\n    threshold: 500\n    statistic: Average\n    period: 60\n    evaluationPeriods: 1\n    comparisonOperator: GreaterThanOrEqualToThreshold\n    treatMissingData: missing\n  functionThrottles:\n    namespace: 'AWS/Lambda'\n    metric: Throttles\n    threshold: 1\n    statistic: Sum\n    period: 60\n    evaluationPeriods: 1\n    datapointsToAlarm: 1\n    comparisonOperator: GreaterThanOrEqualToThreshold\n    treatMissingData: missing\n```\n\n## Disabling default alarms for specific functions\n\nDefault alarms can be disabled on a per-function basis:\n\n```yaml\ncustom:\n  alerts:\n    alarms:\n      - functionThrottles\n      - functionErrors\n      - functionInvocations\n      - functionDuration\n\nfunctions:\n  bar:\n    handler: bar.handler\n    alarms:\n      - name: functionInvocations\n        enabled: false\n\n```\n\n## Additional dimensions\n\nThe plugin allows users to provide custom dimensions for the alarm. Dimensions are provided in a list of key/value pairs {Name: foo, Value:bar}\nThe plugin will always apply dimension of {Name: FunctionName, Value: ((FunctionName))}, except if the parameter `omitDefaultDimension: true` is passed. For example:\n\n```yaml\n    alarms: # merged with function alarms\n      - name: fooAlarm\n        namespace: 'AWS/Lambda'\n        metric: errors # define custom metrics here\n        threshold: 1\n        statistic: Minimum\n        period: 60\n        evaluationPeriods: 1\n        comparisonOperator: GreaterThanThreshold\n        omitDefaultDimension: true\n        dimensions:\n          -  Name: foo\n             Value: bar\n```\n\n```json\n'Dimensions': [\n                {\n                    'Name': 'foo',\n                    'Value': 'bar'\n                },\n            ]\n```\n\n## Using Percentile Statistic for a Metric\n\nStatistic not only supports SampleCount, Average, Sum, Minimum or Maximum as defined in CloudFormation [here](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cw-alarm.html#cfn-cloudwatch-alarms-statistic), but also percentiles. This is possible by leveraging  [ExtendedStatistic](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cw-alarm.html#cfn-cloudwatch-alarms-extendedstatistic) under the hood. This plugin will automatically choose the correct key for you. See an example below:\n\n```yaml\ndefinitions:\n  functionDuration:\n    namespace: 'AWS/Lambda'\n    metric: Duration\n    threshold: 100\n    statistic: 'p95'\n    period: 60\n    evaluationPeriods: 1\n    datapointsToAlarm: 1\n    comparisonOperator: GreaterThanThreshold\n    treatMissingData: missing\n    evaluateLowSampleCountPercentile: ignore\n```\n\n## Using a Separate CloudFormation Stack\n\nIf your Serverless CloudFormation stack is growing too large and you're running out of resources,\nyou can configure the plugin to deploy a separate stack for the CloudWatch resources. The default\nbehaviour is to create a stack with a \"-alerts\" suffix in the stack name.\n\n    custom:\n      alerts:\n        externalStack: true\n\nYou can customize the name suffix:\n\n    custom:\n      alerts:\n        externalStack:\n          nameSuffix: Alerts\n\nThe separate stack will be automatically deployed after you've deployed your main Serverless\nstack. It will also be automatically removed if you remove your main stack.\n\nYou can also enable the external stack on the command line with `sls deploy --alerts-external-stack`\nwhich is equivalent to adding `externalStack: true` to the configuration.\n\n## Dashboards\n\nThe plugin can create dashboards automatically for basic metrics.\n\nDefault setup for a single dashboard:\n```yaml\ndashboards: true\n```\n\nCreate a vertical dashboard:\n```yaml\ndashboards: vertical\n```\n\nCreate dashboards only in specified stages:\n```yaml\ndashboards:\n  stages:\n    - production\n    - staging\n  templates:\n    - default\n```\n\n## License\n\nMIT © [A Cloud Guru](https://acloud.guru/)\n\n\n[npm-image]: https://badge.fury.io/js/serverless-plugin-aws-alerts.svg\n[npm-url]: https://npmjs.org/package/serverless-plugin-aws-alerts\n[travis-image]: https://travis-ci.org/ACloudGuru/serverless-plugin-aws-alerts.svg?branch=master\n[travis-url]: https://travis-ci.org/ACloudGuru/serverless-plugin-aws-alerts\n[daviddm-image]: https://david-dm.org/ACloudGuru/serverless-plugin-aws-alerts.svg?theme=shields.io\n[daviddm-url]: https://david-dm.org/ACloudGuru/serverless-plugin-aws-alerts\n[codecov-image]: https://codecov.io/gh/ACloudGuru/serverless-plugin-aws-alerts/branch/master/graph/badge.svg?token=uC4maLoz3W\n[codecov-url]: https://codecov.io/gh/ACloudGuru/serverless-plugin-aws-alerts\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FACloudGuru%2Fserverless-plugin-aws-alerts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FACloudGuru%2Fserverless-plugin-aws-alerts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FACloudGuru%2Fserverless-plugin-aws-alerts/lists"}