Getting Started with Events
Have you heard about Proactive Ops, but don’t know where to start?
Do you know all the tools and services you use across your environment? A Proactive Ops platform needs to collect events from all your tools, listing them is a great place to start.
Review all the phases of your software lifecycle, identifying all the tools and services you use. What version control platform do you use? What ticketing system do your product and engineering teams use? Does ops use the same one? How do you do uptime monitoring? Keep going, you’ll find more.
Do you already have this inventory of tools properly recorded? If not, now is a perfect time to do it. Create a table, like the one below, in a markdown document (or spreadsheet 🙄) and copy the information into the first two columns of the table.
To complete the third and fourth columns, look for your tool in Amazon’s EventBridge integration page. If it is there, fantastic! You can use the EventBridge integration. If not, you’ll need to rely on Webhooks. Start searching for [tool] webhook to find the documentation. Add the links as you go.
Finally track down the OpenAPI spec file for the service. Generally you’ll find it - or the docs page that references the spec - by searching for [tool] openapi spec.
If you’re in the unfortunate situation of using a tool that only offers a postman collection, consider replacing it. If that isn’t an option, explore using postman2openapi as an intermediate step to convert the collection to a spec file.
| Tool | Purpose | Event Type | Event Docs | OpenAPI Spec |
|---|---|---|---|---|
| GitHub | Version Control CI/CD |
Webhook | https://docs.github.com/en/webhooks/webhook-events-and-payloads | https://github.com/github/rest-api-description/raw/main/descriptions/api.github.com/api.github.com.2022-11-28.yaml |
| Jira | Tickets | Webhook | https://developer.atlassian.com/server/jira/platform/webhooks/ | https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json |
| … | ||||
| PagerDuty | EventBridge and Webhooks | EventBridge: https://support.pagerduty.com/docs/amazon-eventbridge-integration-guide Webhooks: https://developer.pagerduty.com/docs/db0fa8c8984fc-overview |
Events: https://stoplight.io/api/v1/projects/pagerduty-upgrade/api-schema/nodes/reference/events-v2/openapiv3.json?deref=optimizedBundle REST: https://stoplight.io/api/v1/projects/pagerduty-upgrade/api-schema/nodes/reference/REST/openapiv3.json?fromExportButton=true&snapshotType=http_service&deref=optimizedBundle |
|
| Zendesk | Support | EventBridge | https://support.zendesk.com/hc/en-us/articles/4408824521114-Setting-up-the-Zendesk-Events-Connector-for-Amazon-EventBridge | 🤪 https://support.zendesk.com/hc/en-us/community/posts/4408861024794-Zendesk-OpenAPI |
This table is a starting point. It will evolve. Make it your own.
Depending on the size of your organisation, you may want to add a column to track the internal owner of the tool. If you use more than one tenancy within the tool, such as multiple accounts, organisations or teams, you might want to record those. Once you start planning your build out, you should add the tickets in a dedicated column. Later on you might want to track the service accounts you provision for accessing the API.
Expect your table to grow in length and width over time.
Your inventory should be accessible to others in the organisation. You don’t need a custom app to manage this data. Use a wiki page, markdown file in a git repo, Google Sheet or an Excel file stored in M365. Wherever you put it, make sure others can find it.
Once you know what events you have available, you can start to identify which ones you want to consume. Start with the highest impact detections.
Reviewing recent incidents is usually a good place to start. What could have helped you to be aware of the issue sooner? What slowed down the response? What can help avoid it happening in the future? Ideally these will be small, generally applicable controls that you can implement.
In my next post we will look at how to get events from a SaaS into Amazon EventBridge. This will allow us to start routing them to our handlers. 🌊
Need Help?
If you want to adopt Proactive Ops, but you're not sure where to start, get in touch! I am happy to help get you.
Proactive Ops is produced on the unceeded territory of the Ngunnawal people. We acknowledge the Traditional Owners and pay respect to Elders past and present.