Working with Insights and Analytics

1. Viewing Workflow Insights

Example: Accessing Workflow Insights

curl -H "CircleCI-Api-Version: 2.1" \
     -H "Authorization: Bearer <API_TOKEN>" \
     "https://circleci.com/api/v2/workflow/<WORKFLOW_ID>/insights"

Field	Description	Type	Notes
workflow_id	Unique identifier for the workflow	string	Required parameter
project_slug	Project identifier in the format "vcs-type/owner/name"	string	Used for filtering by project
status	Filter by workflow status (success, failed, running)	string	Optional filter
branch	Filter by branch name	string	Optional filter
limit	Number of workflows to return (max 100)	integer	Defaults to 30

Note: Workflow insights are available for workflows that have completed at least once.

Key Metrics Provided

Duration: Total time taken for the workflow
Success Rate: Percentage of successful runs
Resource Usage: CPU and memory consumption
Parallelism: Number of parallel jobs in the workflow

2. Analyzing Build Duration

Metric	Description	Unit	Notes
build_duration	Time taken to complete a build	seconds	Includes all stages: setup, run, cleanup
average_build_duration	Average time across all builds in a project	seconds	Calculated over a specified time window
median_build_duration	Median build time for a project	seconds	More stable than average for skewed data

Example: Build Duration Query

curl -X GET \
  "https://circleci.com/api/v2/project/github/owner/repo/builds?limit=10" \
  -H "Accept: application/json" \
  -H "Circle-Token: <token>"

Note: Build duration data can be used to identify bottlenecks in your CI pipeline and optimize performance.

3. Tracking Success Rates

Metric	Description	Unit	Notes
build_success_rate	Percentage of successful builds out of total builds	Percentage	Calculated as (successful builds / total builds) * 100
workflow_success_rate	Percentage of successful workflows out of total workflows	Percentage	Calculated as (successful workflows / total workflows) * 100
job_success_rate	Percentage of successful jobs out of total jobs	Percentage	Calculated as (successful jobs / total jobs) * 100

Example: Calculating Build Success Rate

// Sample data
const totalBuilds = 150;
const successfulBuilds = 135;

// Calculate success rate
const successRate = (successfulBuilds / totalBuilds) * 100;
console.log("Build Success Rate: " + successRate.toFixed(2) + "%");
// Output: Build Success Rate: 90.00%

Note: Success rates can be tracked over time to identify trends and performance improvements.

4. Identifying Flaky Tests

Property	Description	Notes
flaky_test_detection	Enables detection of flaky tests in your build pipeline	Available in CircleCI Insights
threshold	Number of builds to consider a test flaky	Default: 3 builds

Example: Enabling Flaky Test Detection

version: 2.1
jobs:
  test:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
      - run: npm test
      - store_test_results:
          path: test-results
      - persist_to_workspace:
          root: .
          paths:
            - test-results
workflows:
  version: 2
  build_and_test:
    jobs:
      - test

Note: Flaky test detection is available in CircleCI Insights for projects using the 2.1 configuration version.

How It Works

CircleCI analyzes test results across multiple builds
Tests that fail intermittently are flagged as potentially flaky
Flaky tests are highlighted in the Insights dashboard

5. Viewing Failed Job Analysis

Field	Description	Values
job_name	Name of the job that failed	`build-and-test`
failure_reason	Primary reason for job failure	`test_failure`, `build_error`, `timeout`
failure_message	Detailed error message from the job	`Failed to compile webpack bundle`
duration	Duration of the job in seconds	`120`
start_time	Start time of the job in ISO format	`2025-04-01T10:00:00Z`

Example: Failed Job Analysis

{
  "job_name": "build-and-test",
  "failure_reason": "test_failure",
  "failure_message": "Failed to compile webpack bundle",
  "duration": 120,
  "start_time": "2025-04-01T10:00:00Z"
}

Note: Failed job analysis includes logs and artifacts to help debug issues.

6. Analyzing Cache Performance

Cache Type	Description	Metrics	Usage
Build Cache	Stores build artifacts and dependencies to speed up subsequent builds.	`cache-hit`, `cache-miss`, `cache-size`	Use in `steps` to restore and save cache.
Docker Layer Cache	Caches Docker layers to speed up image builds.	`docker-cache-hit`, `docker-cache-miss`	Enabled by default in Docker executor.
Artifacts Cache	Stores build artifacts for later use in workflows.	`artifact-cache-hit`, `artifact-cache-miss`	Configured via `save_cache` and `restore_cache`.

Example: Cache Performance Metrics

jobs:
  build:
    steps:
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package-lock.json" }}
            - v1-dependencies-
      - run:
          name: Install Dependencies
          command: npm ci
      - save_cache:
          key: v1-dependencies-{{ checksum "package-lock.json" }}
          paths:
            - node_modules

Note: Cache performance can be analyzed in the Insights dashboard under Cache Performance tab.

Key Metrics to Monitor

cache-hit: Percentage of builds that successfully restored cache.
cache-miss: Number of builds that had to rebuild from scratch.
cache-size: Size of the cache in MB or GB.

7. Tracking Build Frequency

Property	Description	Values	Notes
build.frequency	How often builds are triggered	`daily`, `weekly`, `monthly`	Configurable in project settings
build.count	Number of builds in a given period	Integer	Used for analytics dashboards

Example: Build Frequency Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Run Tests
          command: npm test

workflows:
  version: 2
  daily-build:
    triggers:
      - schedule:
          cron: "0 0 * * *"
          branches:
            only:
              - main
    jobs:
      - build

Note: Build frequency can be tracked via CircleCI's Insights dashboard or API endpoints.

8. Using Credits Dashboard

Example: View Credit Balance

curl -H "CircleCI-Api-Key: <API_TOKEN>" \
  https://circleci.com/api/v2/credit-balance

Field	Description	Value Type
credits_used	Total credits consumed in the current billing period	integer
credits_remaining	Credits available for use in the current billing period	integer
credits_limit	Maximum credits allowed in the current billing period	integer

Note: Credits are consumed based on compute time and resource usage in CircleCI.

Warning: If credits are depleted, builds will be paused until the next billing cycle.

Credit Usage Summary

Credits are used for running builds, caching, and other CircleCI services.
Credits can be viewed in the Credits Dashboard or via API.
Each organization has a credit limit based on its plan.

9. Monitoring Parallelism Usage

Property	Description	Values	Notes
parallelism	Number of parallel jobs to run	`1` to `20`	Configurable in config.yml or via UI
max_parallelism	Maximum allowed parallel jobs	`1` to `50`	Set in project settings or via API

Example: Configuring parallelism in config.yml

version: 2.1
jobs:
  build:
    parallelism: 4
    steps:
      - checkout
      - run: echo "Running on parallel job"

Note: Parallelism is limited by your CircleCI plan's resource allocation.

Usage Guidelines

Use parallelism to distribute workload across multiple containers
Monitor resource usage in Insights dashboard for optimal performance
Higher parallelism may increase build times due to overhead

10. Exporting Insights Data

Example: Exporting Pipeline Metrics

curl -H "CircleCI-Api-Version: 2.1" \
     -H "Authorization: Bearer <API_TOKEN>" \
     "https://circleci.com/api/v2/project/github/ORG/REPO/pipeline?limit=10" \
     | jq '.items[] | {pipeline_id: .id, status: .status, created_at: .created_at}'

Field	Description	Notes
pipeline_id	Unique identifier for the pipeline	Used for tracking and querying specific pipelines
status	Current status of the pipeline (e.g., success, running)	Helps in monitoring and analyzing workflow performance
created_at	Timestamp when the pipeline was created	Useful for time-series analysis and reporting

Note: The API endpoint returns a maximum of 100 pipelines per request. Use pagination to retrieve more data.

Example: Exporting Workflow Metrics

curl -H "CircleCI-Api-Version: 2.1" \
     -H "Authorization: Bearer <API_TOKEN>" \
     "https://circleci.com/api/v2/workflow?pipeline_id=<PIPELINE_ID>&limit=50" \
     | jq '.items[] | {workflow_id: .id, name: .name, status: .status}'

Field	Description	Notes
workflow_id	Unique identifier for the workflow	Used to correlate workflows with pipelines
name	Name of the workflow as defined in config.yml	Helps identify specific workflows within a pipeline
status	Overall status of the workflow (e.g., success, failed)	Used for performance and error tracking

Warning: Ensure that the API token has appropriate permissions to access pipeline and workflow data.

Exporting Insights Data Summary

Use the CircleCI API to fetch pipeline and workflow data
Filter and transform data using tools like jq
Export to CSV or JSON for external analysis tools
Implement pagination to handle large datasets