# Celero makes benchmarking a library, not a profiler session

> Celero is a C++14 benchmarking library that links into your test binary, runs each case many times, keeps the fastest measurement and reports results as Markdown tables, CSV or JUnit XML. It is aimed at teams who want benchmarking in CI without buying or wrestling with an external measurement tool.

**DigitalInBlue/Celero** — C++ Benchmark Authoring Library/Framework

- Repository: https://github.com/DigitalInBlue/Celero
- Stars: 865 · Forks: 96
- Language: C++
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/digitalinblue-celero

## A library you link in, not a profiler you attach

The pitch is a small library that can be added to a C++ project and perform benchmarks in a way that is easy to reproduce, share and compare among individual runs, developers or projects. Celero uses a framework similar to that of GoogleTest to make its API more natural to use and integrate into a project, and the stated ambition is to make automated benchmarking as much a part of the development process as automated testing. That is the whole difference in approach against the alternatives the project names, such as Intel VTune Amplifier, SmartBear AQTime and Valgrind. Those tools live outside the application and attach to a running program. Celero lives inside it, becomes part of your test executable, and produces results that land in a repository next to the code rather than on a developer machine.

## Why the fastest run is the one that counts

The Background section of the documentation is a short argument about measurement noise, and it explains the design decisions that follow. The goal is to measure t, the time to execute the code under test. In practice you measure t plus noise: clock resolution noise, operating system background operations, test setup and teardown, framework overhead, and other unrelated system activity. Since those contributors fluctuate over time, the approach is to make many measurements but keep only the smallest total, because the smallest total carries the smallest noise contribution and sits closest to the actual time t. This is why Celero is not trying to be a sampling profiler. It repeats a case and reduces it, which is a different and much simpler statistical question than attributing time to a call stack.

## Baselines, and the _TEST macros that turn runs into CI gates

A single number on its own carries little meaning, so the documentation insists on a baseline, ideally a classic or pure solution to the same problem. The example is that saying a fancy sorting algorithm sorted a million elements in 10 milliseconds is not sufficient, while compared against a quicksort baseline you can say it is 50% faster, which is a meaningful measurement. Celero wires that idea into its CI story. The JUnit output option requires benchmarks to use the _TEST version of the macros and to specify an expected baseline multiple, and when the test exceeds that multiple the JUnit output indicates a failure. So a benchmark can act as a regression gate in a pipeline rather than a number someone reads once. The feature list also names support for fixed-time benchmark baselines, which is the variant for measuring a fixed duration instead of a fixed iteration count.

## Adding Celero to a project with CMake, Conan or VCPKG

Celero uses CMake to provide cross-platform builds and requires a modern C++ compiler supporting C++14, with Windows, Linux and OSX listed as supported targets. The project can be installed using CMake, Conan or VCPKG, and the repository root carries a vcpkg.json manifest. One dependency note applies to the build rather than to the library: as of v2.7, Celero requires the developer to provide GoogleTest in order to build the unit tests, and the project suggests using a package manager such as VCPKG or Conan to provide the latest version. Adopting the library does not mean vendoring a single file. The structure is GoogleTest-like on the consumer side too: all definitions a user needs live in a celero namespace within a single include file, Celero.h, and the macro definitions in that file turn each user benchmark case into its own unique test. For convenience there is a single header file and a CELERO_MAIN macro that supplies a main() for the benchmark project and automatically executes all of the benchmark tests.

## Command line flags for running one group or exporting results

The benchmark executable is controlled by a small set of flags, and this is where Celero stops being a library and becomes a tool you can wire into CI:

```bash
<celeroOutputExecutable> [-g groupNameToRun] [-t resultsTable.csv] [-j junitOutputFile.xml] [-a resultArchive.csv] [-d numberOfIterationsPerDistribution] [-h]
```

The -g flag runs only one benchmark group out of all benchmarks in the executable, which is how you narrow a failing CI job to a single case. -t writes all results to a CSV file, described as very useful when using problem sets to graph performance. -j writes JUnit formatted XML, which is what a CI system consumes. -a builds or updates an archive of historical results, tracking current, best and worst results for each benchmark, so performance over time is visible rather than remembered. -d is marked experimental and builds a plot of four different sample sizes to investigate the distribution of sample results. Console output is formatted as a Markdown table, which is a small detail that matters a lot when the result gets pasted into a pull request.

## Beyond timing: measurements, experiment values and RAM tracking

The feature list extends past wall clock time in two directions. User-defined measurements allow for measuring anything in addition to timing, so a case can record a custom quantity alongside its duration. User-defined experiment values scale test results, sample sizes and user-defined properties for each run, which is how one benchmark function can be exercised across several input sizes without duplicating the case. The library also tracks RAM usage automatically during the experiments. A rich set of timing statistics can be captured to a file, and the timing utilities can be used directly in production code, independent of benchmarks, which is an unusual offer for a test framework and means the measurement helpers do not have to stay behind a test-only boundary. Test fixtures are supported, so shared setup and teardown can be expressed in the usual way.

## Supply chain metadata, licensing and release cadence

The supply chain story is unusually explicit for a small C++ library. SPDX 2.3 SBOMs are committed under sbom/ and published as GitHub Release assets with build provenance attestations, and CI regenerates them on every push and fails if they no longer match the project. Two manifests are produced: one for what you link against, and one for the source distribution, which adds the vcpkg-resolved test and build dependencies, third-party headers vendored under experiments/, and the GitHub Actions that build the project. The key fact for integrators is that Celero has no third-party runtime dependencies, only operating system libraries such as powrprof and psapi on Windows and pthread elsewhere, and GoogleTest is test-only and never enters the installed library. Licensing has a wrinkle worth resolving before you ship: GitHub classifies the repository licence as Other, while the README states Apache 2.0 License and a license.txt file sits in the root, so read that file rather than relying on the badge. The project is copyright John Farrier 2017-2026, carries an OpenSSF Best Practices badge, and lists support from Polyrhythm Software, GitKraken and Microsoft.

## Release rhythm and what the changelog will tell you

The release list shows v2.10.0 on 2026-03-16, v2.9.1 on 2025-06-27 and v2.9.0 on 2023-09-13, and the last push to the repository was on 2026-08-12. The repository is not archived. Read that pattern carefully rather than as a steady cadence, because the gaps between those tags are uneven, with the most recent one arriving in March 2026 and the previous one more than a year earlier. It suggests a project that moves in bursts tied to substantial changes rather than on a schedule. For an adopter the practical question is which version to pin and how much churn a major version brings, and the repository answers both through the repository contents: a CHANGELOG-style practice is implied by the release history, and the tree carries SECURITY.md, SUPPORT.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, an experiments/ directory for anything not yet promoted to the main API, and tools/sbom/ for regenerating the SBOMs locally.

## Conclusion

Celero suits a C++ team that wants a benchmark suite living in the same repository and the same CI pipeline as its unit tests, and that can supply GoogleTest for the unit test build as required since v2.7. It is the wrong choice for profiling a live application or for teams that need instruction level attribution, since the measurement tools the project names for that purpose sit outside the process. Verify first that your compiler supports C++14 and that you install through CMake, Conan or VCPKG rather than copying headers by hand, and check license.txt, because GitHub classifies the repository licence as Other while the README states Apache 2.0.

## FAQ

### How do I install Celero?

Celero uses CMake for cross-platform builds and can be installed using CMake, Conan or VCPKG, and the repository ships a vcpkg.json manifest. It requires a modern C++ compiler supporting C++14, and since v2.7 you must provide GoogleTest to build the unit tests.

### How do I write a Celero benchmark?

You include the single header file Celero.h and use the macros it defines, and you can use the CELERO_MAIN macro to provide a main() that automatically executes all of your benchmark tests. The API is deliberately similar to GoogleTest.

### How do I make Celero benchmarks fail in CI?

Use the JUnit output option and the _TEST version of the macros with an expected baseline multiple. When a test exceeds that multiple, the JUnit output indicates a failure, so the -j flag makes the benchmarks a regression gate.

### Does Celero have any third-party runtime dependencies?

No. The SBOM description states that Celero has no third-party runtime dependencies, only operating system libraries such as powrprof and psapi on Windows and pthread elsewhere. GoogleTest is test-only and never enters the installed library.

### What is the difference between Celero and an external profiler such as Valgrind?

External tools such as Valgrind, Intel VTune Amplifier and SmartBear AQTime attach to or run the application from outside and can be expensive for small teams or cumbersome to use. Celero is a library linked into a C++ project that runs as part of the test suite, with results exported as CSV or JUnit XML.

## Sources

- [DigitalInBlue/Celero on GitHub](https://github.com/DigitalInBlue/Celero)
- [Issues](https://github.com/DigitalInBlue/Celero/issues)
- [README](https://github.com/DigitalInBlue/Celero/blob/master/README.md)
- [Releases](https://github.com/DigitalInBlue/Celero/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/digitalinblue-celero