{"id":16475954,"url":"https://github.com/softprops/serverless-oncall","last_synced_at":"2025-03-23T11:32:56.433Z","repository":{"id":47598348,"uuid":"162144614","full_name":"softprops/serverless-oncall","owner":"softprops","description":"⚡📟 Easily manage oncall for your serverless services","archived":false,"fork":false,"pushed_at":"2021-08-22T18:39:18.000Z","size":271,"stargazers_count":7,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-17T12:00:02.241Z","etag":null,"topics":["oncall","pagerduty","serverless","serverless-framework","serverless-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/softprops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-17T14:41:43.000Z","updated_at":"2021-07-15T21:05:36.000Z","dependencies_parsed_at":"2022-09-06T08:50:58.285Z","dependency_job_id":null,"html_url":"https://github.com/softprops/serverless-oncall","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fserverless-oncall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fserverless-oncall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fserverless-oncall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fserverless-oncall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softprops","download_url":"https://codeload.github.com/softprops/serverless-oncall/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245097158,"owners_count":20560311,"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":["oncall","pagerduty","serverless","serverless-framework","serverless-plugin"],"created_at":"2024-10-11T12:40:59.746Z","updated_at":"2025-03-23T11:32:55.959Z","avatar_url":"https://github.com/softprops.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# serverless-oncall [![Build Status](https://travis-ci.org/softprops/serverless-oncall.svg?branch=master)](https://travis-ci.org/softprops/serverless-oncall) [![npm](https://img.shields.io/npm/v/serverless-oncall.svg)](https://www.npmjs.com/package/serverless-oncall)\n\n\u003e ⚡📟 easly manage oncall for serverless services\n\n## 🤔 Motivation\n\nServerless services facilitate fast develop and deploy cycles. Once in production, these applcations should also have an answer for: \"Okay, so how is this application supported when customers start using it\"? The answer should not be to wait until\ncustomers tell you your service is down.\n\nThe Serverless framework leverages multiple providers that manage many operational aspects of the _runtimes_\nyour application runs on but they do not manage the operational aspects of _your application_ itself. That's up to you.\n\nA number of great monitoring solutions exist and there are even [serverless plugins](https://github.com/ACloudGuru/serverless-plugin-aws-alerts) to leverage them! Serverless oncall fills the gap\nof how you then **act** on these monitoring systems.\n\nServerless oncall leverages [pagerduty](https://www.pagerduty.com/)*, a managed oncall scheduling, dispatch and notification hub, to map your application service to an oncall rotation that\nintended to support its operation. The intended target for this support ideally is the developers that own the service.\n\nThis plugin is intended to pair well with the [AWS Alerts plugin](https://github.com/ACloudGuru/serverless-plugin-aws-alerts) but is not coupled to AWS serverless provider.\n\n## 📦 Install\n\nInstall the plugin with `npm`\n\n```bash\n$ npm i -D serverless-oncall\n```\n\nUpdate your `serverless.yml` file with the following\n\n```yaml\nplugins:\n - serverless-oncall\n\ncustom:\n  oncall:\n    # the escalation_policy you want pager duty alerts associated with\n    escalationPolicy: ${env:PD_ESC_POLICY,''}\n\n    # credential used to authenticate with pagerduty api\n    # visit https://{company}.pagerduty.com/api_keys to create one\n    apiKey: ${env:PD_API_KEY,''}\n\n    # a list of integrations to associate with your oncall service\n    # this will determine where monitoring systems send information to.\n    #\n    # currently only the \"cloudwatch\" and \"transform\" integration are supported but more integrations are\n    # planned for the future\n    # you may omit this configuration if you wish and configure these manually\n    # in the pagerduty web console\n    integrations:\n      - cloudwatch:\n      - tranform:\n          code: 'code here'\n```\n\nThis plugin currently requires a pagerduty api key to interact with the pagerduty api.\n\n💡 You can learn how to get your own api key [here](https://support.pagerduty.com/docs/using-the-api)\n\nIt is recommended to\n**not** inline your api key's value directly in your `serverless.yaml` in plain text to avoid accidently checking it into source control.\nYou can leverage [serverless variables](https://serverless.com/framework/docs/providers/aws/guide/variables/) as you would with other secret credentials to resolve this value without including it in your source code.\n\nThe example above is using [env variables](https://serverless.com/framework/docs/providers/aws/guide/variables#referencing-environment-variables) to resolve these values. You would then invoke a serverless command by providing them\nexternally.\n\n```bash\n$ PD_ESC_POLICY=xxx PD_API_KEY=xxxxxxx npx serverless info\n```\n\nServerless framework provides [many options](https://serverless.com/framework/docs/providers/aws/guide/variables/) for storing these externally from your source code. Pick one.\n\n### Integrations\n\nAs mentioned above the way you intergrate a monitoring systems is with pagerduty.\nThe delivery of this information to your oncall team is key so its worth considering your options\n\n### cloudwatch\n\nThis integration is easy to configure but limited in the way information is delivered.\n\n### transform\n\nThis integration requires some configuration but is more flexible with how information is delivered.\n\nBelow is an example appoach to keeping that configuration managable.\n\nThe `transform` integration lets you provde a snippet of javascript that pager duty will\nrun when it recieves an incident event. This lets you desired how you want your information\nto be delievered and displayed to your oncall team. The example below leverages serverless frameworks ability externalize and dereference data in separate files.\n\n\n```yaml\ncustom:\n  oncall:\n    integrations:\n      # event transform integration (pagerduty's serverless event transformer)\n      - transform:\n          code: \"${file(transformConfig.js):code}\"\n```\n\nThe `transform.code` field is a string of javascript source. This assumes\n`transformConfig.js` is a file that will provide that by loading in\nan `oncallHandler.js` file.\n\n```sh\n$ cat transformConfig.js\nmodule.exports.code = () =\u003e {\n  // read in javascript source\n  return require('fs').readFileSync('oncallHandler.js').toString();\n}\n```\n\n```sh\n$ cat oncallHandler.js\n// https://v2.developer.pagerduty.com/docs/creating-an-integration-inline\nvar helloWorld = {\n  event_type: PD.Trigger,\n  incident_key: PD.inputRequest.body.incident_id,\n  description: PD.inputRequest.body.description,\n  details: PD.inputRequest.body,\n  client: \"Hello world\",\n  client_url: \"https://github.com/softprops/serverless-oncall\"\n};\n​\nPD.emitGenericEvents([helloWorld]);\n```\n\nThis approach also brings the potential of unit testing your transform code as it is now\njust a standalone javascript file. The\n[pagerduty docs](https://v2.developer.pagerduty.com/docs/creating-an-integration-inline)\nmay help here.\n\n## 🎙️ Commands\n\nserverless-oncall adds new commands to your servleress vocabulary. You can discover these new commands though the built-in `--help` option\n\n```bash\n$ npx serverless --help | grep oncall\n```\n\n### escalationPolicies\n\nIn order to create or update an oncall service you will need to first select an appropriate escalation policy to associate the service with. You can think of roughly as selecting the target group of individuals to be notified. This plugin provides the `escalationPolicies` command for conveniene of listing these but does not manage them directly. Use the pagerduty UI do that instead.\n\n```bash\n$ npx serverless oncall escalationPolicies\n```\n\nYour organization will likely have more than one time. The list above will include escalations for\nall teams. To limit this list to a single (your) team use the `-t` flag and provide that teams pagerduty team identifier.\n\n```bash\n$ npx serverless oncall escalationPolicies -t {team}\n```\n\n### sync\n\nThis command will use the information described your serverless.yml oncall resource\nto create resources with a remote provider, currently pagerduty.\n\n```bash\n$ npx serverless oncall sync\n```\n\n### info\n\nserverless-oncall integrates itself with the serverless built-in command, [info](https://serverless.com/framework/docs/providers/aws/cli-reference/info/) and prints\nout high level information about the state of its associated oncall service. If you just want a quick\nlink to the oncall service, use this.\n\n```bash\n$ npx serverless info\n```\n\n\\* serverless-oncall may support other oncall providers in the future\n\n## 🚧 Planned work\n\n* interface design. the current design relects an minimum viable design. this is subject to change.\n* support more integrations\n* support more oncall service providers\n\n## 👯 Contributing\n\nContributions are welcome. Please read [our contributing doc](CONTRIBUTING.md) for more information.\n\nDoug Tangren (softprops) 2018","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Fserverless-oncall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftprops%2Fserverless-oncall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Fserverless-oncall/lists"}