sredocs

README

sredocs

sredocs is to turn postmortems, charters and other SRE docs into machine readable data for analysis while retaining human readability properties.

This repository contains code for downloading postmortems and/or charters following certain template(s) from Google Docs, parsing the data to CSV and support for uploading the result to Google BigQuery.

Here is a demo dashboard for incident analysis using this, Google Data Studio and BigQuery. It contains an interactive report with information related to five dummy postmortems.

sredocs currently parses postmortems using a single specific template (sample) and charter that will be published separately later.

Download

Here is how to use the download mode:

1. Go to https://console.developers.google.com. I'd recommend creating a new project called "sredocs".
2. Switch to that project. Search for "Google Drive API" then enable it.
3. Go to APIs & Services -> Credentials.
4. Click on "Create credentials" then select Service account key.
5. Give your Service account key a name, e.g "sredocs".
6. Take note of its address (looks like an email address). Do not assign it a role while creating it.
7. Save the private key (it will be automatically downloaded).
8. Switch to Google Drive.
9. Give your service account address, e.g sredocs@...iam.gservice... view access to the folder with SRE docs.
10. Pass the private key to sredocs via -download_credentials_path.
11. Run mkdir <download_dir>
12. Run sredocs -mode=download -cloud_credentials=<creds.json> -download_folder=<docs_folder> -download_destination=<download_dir>

Parse

Here is how to use the parse mode:

1. Run mkdir <parsed_dir>
2. Run sredocs -mode=parse -parse_kind=auto -parse_path=<download_dir> -parse_output_path=<parsed_dir>

Upload

Here is how to use the upload mode:

1. Follow the instructions for Download first.
2. Go to https://console.developers.google.com.
3. Navigate to IAM & Admin.
4. Click on the Add button.
5. Search for your service account, e.g sredocs@... Give it the BigQuery Admin role.
6. Run sredocs -mode=upload -cloud_credentials=<creds.json> -upload_path=<parsed_dir> -upload_project=<org:project> -upload_dataset=<sredocs> -upload_table=<sredocs_20190603> -upload_truncate=true

BYOP

You can also bring your own parser.

type Parser interface {
        CompileRegex(fields []string) ([]*regexp.Regexp, error)
        Parse(fields []string, b []byte) (*bytes.Buffer, error)
        CSVHeader(regexps []*regexp.Regexp) []string
        NamedGroup(field string) string
        Save(buf *bytes.Buffer, filename string) error
}

You will have to modify charter/* and postmortem/* to switch away from the DefaultParser.

You can also extend sredocs by adding a new kind of document by using charter/* as a template.