Add forecast lab

2023-09-07 14:53:55 -04:00
parent 0d8457a47d
commit d86f482d72
2 changed files with 197 additions and 0 deletions
@@ -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 <source-file-path> (REQUIRED)  The file path(s) to existing jobs data.
+  -o, --output-dir <output-dir> (REQUIRED)          The location for any output files.
+  --start-date <start-date>                         The start date of the forecast analysis in YYYY-MM-DD format. [default: 9/12/2022 12:42:39 PM]
+  --time-slice <time-slice>                         The time slice in seconds to use for computing concurrency metrics. [default: 60]
+  --credentials-file <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)
@@ -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"
+  }
+]