Development

This chapter is dedicated to those who dared to write some code for this project.

Development environment

Here is how to create a local development environment:

  1. First of all install everything described in Prerequisites.

  2. In addition to that, a developer needs to install a debug-build of CPython. It is better to use it when developing extensions for CPython - you’ll get meaningful errors messages in case of reference-counting errors for example.

    On Ubuntu 18.04 it could be done with the following command:

    sudo apt-get install python3.8-dbg

  3. Install Tox with version above 3.

  4. Use Tox to deploy the development virtualenv:

    tox -edev

  5. Activate the development virtualenv: . .tox/dev/bin/activate.

This is it.

Architecture overview

Gauge is built upon three main entities - collectors, aggregators, exporters.

  • Collectors - collect raw data which is just snapshots of the current state of execution.

  • Aggregators - aggregate the raw data collected by the collector. The task of an aggregator is to turn a collection of raw snapshots into something meaningful:

    • Spans - potentially incomplete calls with start and end represented as separate objects).
    • Calls - complete calls with known start and end.
    • Statistics - summary aggregated data (like it’s done in PStats module in Python’s standard library).

  • Exporters - the task of the exporters is to simply save data or push it to some kind of remote monitoring service.

Commit message format

  • First line - 50 symbols max. in the imperative mood, conforming to punctuation rules of the English language.
  • Subsequent lines - 72 symbols max.
  • Optionally - comma-separated list of referenced issues/PRs on the last line of the message body, preceded by an empty line.

Example good commit message

Add foo() method into Bar class.

foo() does a really important thing and this makes Bar even more
awesome.

#42, #36, #11

Contribution guide

Nothing complex for now - just create an issue on the issue tracker or comment on the existing one and then make a pull request ;)