From d86f482d72e1a57777656718619955caa3d76ab5 Mon Sep 17 00:00:00 2001 From: j-dunham Date: Thu, 7 Sep 2023 14:53:55 -0400 Subject: [PATCH] Add forecast lab --- bitbucket/3-forecast.md | 107 ++++++++++++++++++ .../bootstrap/source_files/forecast_jobs.json | 90 +++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 bitbucket/bootstrap/source_files/forecast_jobs.json diff --git a/bitbucket/3-forecast.md b/bitbucket/3-forecast.md index 447d5f3..f8efe2c 100644 --- a/bitbucket/3-forecast.md +++ b/bitbucket/3-forecast.md @@ -1 +1,108 @@ # Forecast potential build runner usage + +In this lab you will use the `forecast` command to forecast potential GitHub Actions usage by computing metrics from completed pipeline runs in Bitbucket. + +## Prerequisites + +1. Followed the steps [here](./readme.md#configure-your-codespace) to set up your GitHub Codespaces environment. +2. Completed the [configure lab](./1-configure.md#configuring-credentials). + +## Perform a forecast + +Answer the following questions before running the `forecast` command: + +1. What workspace do you want to run the forecast for? + - **actions-importer** +2. What is the date you want to start forecasting from? + - **2023-08-03**. This value defaults to the date one week ago, however, you should use a start date that will show a representative view of typical usage. +3. Where do you want to store the results? + - **tmp/forecast** + +### Steps + +1. Navigate to your codespace terminal +2. Run the following command from the root directory: + + ```bash + gh actions-importer forecast bitbucket --workspace actions-importer --start-date 2023-08-03 --output-dir tmp/audit --source-file-path bitbucket/**/source_files/*.json + ``` + > Note: This uses `--source-file-path` to specify the source of the usage date, which would typically be left out of the command during normal usage. This option is explained in more depth in a later section. + +3. The command will list all the files written to disk when the command succeeds. + ```console + [2023-09-07 18:26:22] Logs: 'tmp/audit/log/valet-20230907-182622.log' + [2023-09-07 18:26:22] Forecasting 'https://bitbucket.org/actions-importer' + [2023-09-07 18:26:22] Output file(s): + [2023-09-07 18:26:22] tmp/audit/forecast_report.md + ``` +## Review the forecast report + +The forecast report, logs, and completed job data will be located within the `tmp/forecast` folder. + +1. Find the `forecast_report.md` file in the file explorer. +2. Right-click the `forecast_report.md` file and select `Open Preview`. +3. This file contains metrics used to forecast potential GitHub Actions usage. + +### Total + +The "Total" section of the forecast report contains high level statistics related to all the jobs completed after the `--start-date` CLI option: + +```md +- Job count: **8** +- Pipeline count: **8** + +- Execution time + + - Total: **11 minutes** + - Median: **1 minutes** + - P90: **4 minutes** + - Min: **1 minutes** + - Max: **4 minutes** + +- Concurrent jobs + + - Median: **0** + - P90: **0** + - Min: **0** + - Max: **1** +``` + +Here are some key terms of items defined in the forecast report: + +- The `job count` is the total number of completed jobs. +- The `pipeline count` is the number of unique pipelines used. +- `Execution time` describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of GitHub-hosted runners. + - This metric is correlated to how much you should expect to spend in GitHub Actions. This will vary depending on the hardware used for these minutes. You can use the [Actions pricing calculator](https://github.com/pricing/calculator) to estimate a dollar amount. +- `Concurrent jobs` metrics describe the amount of jobs running at any given time. This metric can be used to define the number of runners a customer should configure. + +Additionally, these metrics are defined by hosted and self-hosted runners. + +## Forecasting multiple providers + +You can examine the available options for the `forecast` command by running `gh actions-importer forecast --help`. When you do this you will see the `--source-file-path` option: + +```console +$ gh actions-importer forecast -h +Options: + --source-file-path (REQUIRED) The file path(s) to existing jobs data. + -o, --output-dir (REQUIRED) The location for any output files. + --start-date The start date of the forecast analysis in YYYY-MM-DD format. [default: 9/12/2022 12:42:39 PM] + --time-slice The time slice in seconds to use for computing concurrency metrics. [default: 60] + --credentials-file The file containing the credentials to use. + --no-telemetry Boolean value to disallow telemetry. + --no-ssl-verify Disable ssl certificate verification. + --no-http-cache Disable caching of http responses. + -?, -h, --help Show help and usage information +``` + +You can use the `--source-file-path` CLI option to combine data from multiple reports into a single report. This becomes useful if you use multiple CI/CD providers and want to get a holistic view of the runner usage. This works by using the `.json` files generated by `forecast` commands as space-delimited values for the `--source-file-path` CLI option. Optionally, this value could be a glob pattern to dynamically specify the list of files (e.g. `**/*.json`). + +Below is a example command that would generate a report for all files matching `tmp/**/jobs/*.json`: + +```bash +gh actions-importer forecast --source-file-path tmp/**/jobs/*.json --output-dir tmp/forecast-combined +``` + +## Next steps + +[Perform a dry-run migration of a Bitbucket pipeline](4-dry-run.md) diff --git a/bitbucket/bootstrap/source_files/forecast_jobs.json b/bitbucket/bootstrap/source_files/forecast_jobs.json new file mode 100644 index 0000000..589d01c --- /dev/null +++ b/bitbucket/bootstrap/source_files/forecast_jobs.json @@ -0,0 +1,90 @@ +[ + { + "id": "{d47f79cd-9cb6-4ac8-8e85-ba448edab7df}", + "build_number": "{d47f79cd-9cb6-4ac8-8e85-ba448edab7df}", + "result": "pipeline_step_state_completed_successful", + "queue_time": null, + "start_time": "2023-09-07T08:00:46+00:00", + "finish_time": "2023-09-07T08:00:49+00:00", + "definition_id": "{a990d84b-2229-4fb5-addf-9d85a20568bb}", + "runner_name": null, + "runner_group": "hosted" + }, + { + "id": "{91fa4c59-31e6-48e8-9db2-24133dd820c6}", + "build_number": "{91fa4c59-31e6-48e8-9db2-24133dd820c6}", + "result": "pipeline_step_state_completed_successful", + "queue_time": null, + "start_time": "2023-09-06T08:00:37+00:00", + "finish_time": "2023-09-06T08:00:43+00:00", + "definition_id": "{fa347742-00ea-4a28-9866-c5257b15d719}", + "runner_name": null, + "runner_group": "self-hosted" + }, + { + "id": "{dd548f45-405b-4efe-9413-15a2cd585f53}", + "build_number": "{dd548f45-405b-4efe-9413-15a2cd585f53}", + "result": "pipeline_step_state_completed_successful", + "queue_time": null, + "start_time": "2023-09-05T08:00:56+00:00", + "finish_time": "2023-09-05T08:03:59+00:00", + "definition_id": "{6112d63f-6e28-4464-b9aa-7f24eb34e00f}", + "runner_name": null, + "runner_group": "self-hosted" + }, + { + "id": "{4eb4521a-9159-4ff6-b328-c62cac52131f}", + "build_number": "{4eb4521a-9159-4ff6-b328-c62cac52131f}", + "result": "pipeline_step_state_completed_successful", + "queue_time": null, + "start_time": "2023-09-04T08:00:19+00:00", + "finish_time": "2023-09-04T08:00:23+00:00", + "definition_id": "{c7e80d72-f205-4603-8569-f074191187e4}", + "runner_name": null, + "runner_group": "hosted" + }, + { + "id": "{12c99c31-d12d-49e5-9d38-83c5e226b0a5}", + "build_number": "{12c99c31-d12d-49e5-9d38-83c5e226b0a5}", + "result": "pipeline_step_state_completed_successful", + "queue_time": null, + "start_time": "2023-09-03T08:00:10+00:00", + "finish_time": "2023-09-03T08:00:13+00:00", + "definition_id": "{fc61a473-8718-4ddd-a89b-3343db294726}", + "runner_name": null, + "runner_group": "hosted" + }, + { + "id": "{190e777d-3ff3-4f3c-9f77-cbf03e69415b}", + "build_number": "{190e777d-3ff3-4f3c-9f77-cbf03e69415b}", + "result": "pipeline_step_state_completed_successful", + "queue_time": null, + "start_time": "2023-09-02T08:00:35+00:00", + "finish_time": "2023-09-02T08:00:38+00:00", + "definition_id": "{fc5bae20-556d-43db-9be4-80bbe1eb1995}", + "runner_name": null, + "runner_group": "hosted" + }, + { + "id": "{a597affa-c2a2-441b-b91b-e80751ba3ecc}", + "build_number": "{a597affa-c2a2-441b-b91b-e80751ba3ecc}", + "result": "pipeline_step_state_completed_successful", + "queue_time": null, + "start_time": "2023-09-01T08:00:48+00:00", + "finish_time": "2023-09-01T08:00:52+00:00", + "definition_id": "{0117b0f0-dcd3-4680-812f-6162cb919d90}", + "runner_name": null, + "runner_group": "hosted" + }, + { + "id": "{ea0e658d-86d8-40cc-90e5-b69ceff1bf4e}", + "build_number": "{ea0e658d-86d8-40cc-90e5-b69ceff1bf4e}", + "result": "pipeline_step_state_completed_successful", + "queue_time": null, + "start_time": "2023-08-31T08:00:16+00:00", + "finish_time": "2023-08-31T08:00:20+00:00", + "definition_id": "{32a1db46-05b4-405f-aeac-6a34eb04f587}", + "runner_name": null, + "runner_group": "hosted" + } +] \ No newline at end of file