Credit Usage Review/Tools

Overview:

CircleCI offers multiple tools and resources to monitor and extract usage data. 

Prerequisites  

These changes can only be made by an organization's admin. To help identify your organization's admins, please reference the articles below:

• Am I an Org Admin?
• How do I find my org admins?

Usage Tab 

CircleCI offers a Usage Tab built right into the UI. This can be used to review usage from the past 12 months. 

Usage API

We’ve heard the feedback around the need for more data, and are excited to provide exactly that through our new Usage API. Today, teams have full access to this data, all the way down to the near-lowest level (individual job run) of granularity possible. By providing you with direct access to this data, we want teams to:

• Be able to identify where compute and resources are being spent
• Feel empowered to fully optimize pipelines, workflows, and jobs
• Forecast usage and credit consumption more accurately, and 
• Provide full transparency on usage to all internal stakeholders, directly

The Usage API allows you to pull data from all of your orgs in a single API call, set the date range from which to pull data (any 32-day window or less) from the past 13 months, up to 10x per day. The results are returned in the form of a URL, from which you’ll be able to download the CSV result set. Teams can automate the process for ingesting the data into their own data warehouse, and query/visualize it as they please. 

Below you will find a visual representation of the data’s shape and flow:

Let’s look at how to utilize the API. First, head to your Organization Settings, and locate your Organization ID. Then, navigate to your User Settings to create a Personal Access Token. To access your User Settings, click the icon located at the bottom of the left-hand side. 

Now, you’re ready to get started with the first API request: creating a usage export. This will kick off the job that gathers the respective organizations data, through a POST request: 

In the response, you will find a usage_export_job_id, which you will use in the following request. With the data established and the usage_export_job_id handy, we then use that to make the following GET request, to gather that data:

The download_urls returned will provide a downloadable GZIP file, which you’ll decompress before the data is viewable.

It’s important to note that the GET request does not have the same restrictions as the POST request (POST request rate limited to 10). The endpoint for the GET request should be polled until the download_urls becomes available. The returned state field will change to completed when the urls are available. You may find you’ll still receive a URL, even if data is not available for the provided date range. We plan to make the absence of data more clear, potentially through a special status returned from the GET request.

For supporting documentation, head here. You will find details around the available report fields, restrictions, requirements, and a visual guide on how to use the API.

API Overview on Youtube

Insights Page

The CircleCI Insights page provides an overview of the health and usage of your projects’ build processes. It includes time-series and aggregated data on credit usage, success rates, and pipeline duration. However, it's important to note that Insights is not a financial reporting tool and should not be used for precise credit reporting. The data is not real-time and there may be up to a 24-hour delay 

The Insights page shows specific numbers related to workflow run, workflow duration, credits consumed, and the overall success rate for all projects in your organization over a selected time range. The ranges you can choose are 24 hours, seven, 30, 60, and 90 days

Insights can also provide information about the most failed tests, their suite, failure frequency, as well as similar data around the slowest failed tests To access a specific project’s Insights, view a pipeline’s workflow and click the Insights button. Alternatively, you may access the Insights page by opening a pipeline’s Actions menu while viewing the pipelines dashboard 

The Insights workflow overview provides metrics plotted over time for all branches, or a select branch, of a particular project workflow. The following data is charted under the workflow overview:
- Status (success versus failed) of up to 100 most recent workflow runs
- Workflow success rate
- Workflow duration (50th versus 95th percentile)
- Workflow credit usage

You can also view the following cumulative data on a per-job basis:
- Total credits used
- Duration (95th percentile)
- Total runs
- Success rate
- Compute usage (average and max for CPU and RAM)