109 lines
5.3 KiB
Markdown
109 lines
5.3 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**. By default, the value is set to one week ago, but it's recommended that you choose a start date that provides 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/forecast --source-file-path bitbucket/**/source_files/*.json
|
|
```
|
|
> Note: The `--source-file-path` option is not required and is used throughout this lab to convert files that are stored locally. This can be omitted and GitHub Actions Importer will programmatically fetch historical pipeline runs using the Bitbucket REST APIs.
|
|
|
|
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/forecast/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)
|