cxxet = C++ easy tracing

• Introduction
  • Trace Event Format
  • Competition
• Examples
• License
• Contributing
• Development and management in general
  • Environments with bash
    • Preparing & using docker environment
      • Command line
      • Devcontainer for VS Code
    • Benchmarking
      • Micro benchmarks
      • Large benchmarks
• TODO

Introduction

TODO (#118):

1. see/mention/interlink (even more ...) presentation about intrusive & visual profiling for Prague C++ meetup here
2. how to include it in yor project - short cmake's "fetch content" example
3. add short example of how to intrusively instrument code (maybe snippet of some example?!)
4. screenshot of how it looks like when displayed, e.g. via Perfetto

Trace Event Format

Right now, only the Trace Event Format format is currently used & available, and seems sufficient.

Competition

TODO (#119) explore more & compare with:

• NVIDIA Nsight Systems
• Tracy
  • TODO would it be feasible to implement Tracy's internal format too?!
  • using Tracy profiler to display saved traces
• TODO explore this nice article
  • clang xray ...
• Perfetto Trace Processor
  • Doesn't seem to provide API for tracing itself, only processing results.
  • Citation: "The Trace Processor is a C++ library (/src/trace_processor) that ingests traces encoded in a wide variety of formats ..." => TODO explore more or not?

Examples

Examples are here. They should sufficiently demonstrate how to use cxxet in your code. By the way, they are also used for testing cxxet itself, so they assure that it works as intended the tests require!

License

LGPLv3 -> COPYING & COPYING.lesser

Your application can be proprietary, commercial, or under any license. You can link cxxet dynamically or statically without releasing your application's source code, as long as You:

• include copy of LGPLv3 license with distribution, preserve cxxet's copyright notices and allow users to replace cxxet (provide your object files or ensure dynamic linking remains possible);
• if you modify cxxet itself, those modifications must be released under LGPLv3.

Contributing

Contributions are more than welcome! See CONTRIBUTING.md for details.

Development and management in general

Further details about provided convenience scripts are in scripts/README.md.

Environments with bash

When having bash available, use cxxet_manage.bash for compilation, testing, preparing docker image(s) for development, and so on. Good starting point is to display what is available, e.g.:

$ ./cxxet_manage.bash --help
...
$ ./cxxet_manage.bash compile --help
...

Preparing & using docker environment

Command line

If you don't have all tools/compilers/... available, and don't want to install them "directly" (see their list in respective Dockerfiles), corresponding docker image(s) can be built & used:

# `XYZ` is valid image name or `--help`/`-h`:
$ ./cxxet_manage.bash docker_build_image XYZ # builds given image (or displays help ...)
...
$ ./cxxet_manage.bash docker_interactive XYZ # enters interactive (bash) shell in it (or displays help ...)
...
# all further commands are executed inside via the `cxxet_manage.bash` script too, e.g.:
$ ./cxxet_manage.bash compile ...
...

Devcontainer for VS Code

To reopen this project in VS Code using devcontainer, first build the image & generate the config. file:

# `XYZ` is valid image name
$ ./cxxet_manage.bash docker_build_image XYZ
...
$ ./cxxet_manage.bash docker_devcontainer XYZ
...

After this, VS Code will offer to reopen the project in the container.

Benchmarking

Micro benchmarks

TODO ... using google/benchmark ...

Large benchmarks

First generate some data (or use present one), then adjust the source code and generate "challenger" data, e.g.:

$ ./cxxet_manage.bash benchmarks large --out-dir /tmp/baseline -n 10 -c
...
# adjust source code, recompile, etc. and measure it again:
$ ./cxxet_manage.bash benchmarks large --out-dir /tmp/challenger -n 10 -c
...

Then compare the results, e.g.:

$ bin/release/cxxet_large_bench_compare --verbose /tmp/baseline/large.json /tmp/challenger/large.json | less -M
...

and decide whether the changes were for better or not.

TODO

Maybe create github issues for those?

• clean up this paragraph (#123)
• benchmarking
  • try reimplementing the cxxet::mark::complete to don't hold all the data, but "save" them immediately and update end time (duration) on submit/d-tor (by holding only pointer to this particular record)
• add more output formats (e.g. implied by this conversation: https://chatgpt.com/share/681b2833-c728-8003-9e28-a4e1c1c35196)
  • read e.g. https://www.chromium.org/developers/how-tos/trace-event-profiling-tool/ and fix how it's saved -> e.g. "stacked" markers are properly displayed