109 lines
5.2 KiB
Markdown
109 lines
5.2 KiB
Markdown
# 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)
|