



Gauge 0.0.2 documentation

Gauge[¶](#gauge "Permalink to this headline")

=============================================

[![Documentation Status](https://readthedocs.org/projects/gauge/badge/?version=latest)](https://gauge.readthedocs.io/en/stable/?badge=latest)

Low-overhead streaming (or continuous) OpenTracing-compatible Python profiler.

Quick links[¶](#quick-links "Permalink to this headline")

---------------------------------------------------------

| Documentation | <https://gauge.readthedocs.io/en/stable/> |

| Issue tracker | <https://github.com/AndreiPashkin/gauge/issues/> |

Why another profiler?[¶](#why-another-profiler "Permalink to this headline")

----------------------------------------------------------------------------

The idea is to make a profiler which would be able to continuously *stream*

the profile data to monitoring software (like [Jaeger](https://www.jaegertracing.io/) or [Elastic APM](https://www.elastic.co/apm/)) and

also, have low-performance overhead so that it would be possible to deploy it on

production. So it would be possible to monitor the performance of a microservice or

some other long-running application in real-time over a long period and explore

historical performance data.

Currently, no open-source alternatives exist that are able to do that.

Features[¶](#features "Permalink to this headline")

---------------------------------------------------

* OpenTracing compatibility.

Specifically with the following APMs:

	+ [Elastic APM](https://www.elastic.co/apm/) (after [this fix](https://github.com/elastic/apm-agent-python/pull/824) is merged).

	+ [Jaeger](https://www.jaegertracing.io/).

* Very low overhead with 100 / samples per second sampling frequency.

* Supports generators/coroutines.

Compatibility[¶](#compatibility "Permalink to this headline")

-------------------------------------------------------------

Currently, the project targets only CPython 3.5+. It is intended to be

compatible with all major operating systems, but currently only tested on

Ubuntu Linux.

Project status[¶](#project-status "Permalink to this headline")

---------------------------------------------------------------

Project in alpha stage of development and is actively worked on.

It just passed the state where the main functionality is working more or less

correctly and it is possible to actually install it and use.

How does it work?[¶](#how-does-it-work "Permalink to this headline")

--------------------------------------------------------------------

The profiler exploits [\_PyThread\_CurrentFrames()](https://github.com/python/cpython/blob/8ecc0c4d390d03de5cd2344aa44b69ed02ffe470/Python/pystate.c#L1155) function of CPython’s

C-API which provides reasonable performance. This function is called with

defined frequency in a background thread which collects raw data which is in

turn aggregated and exported to somewhere in another background thread which is

activated with a much lower frequency.

Alternatives[¶](#alternatives "Permalink to this headline")

-----------------------------------------------------------

| Profiler | Is low-overhead? | Is streaming? | Is commercial? | Is Open-Source? | Has permissive license? |

| --- | --- | --- | --- | --- | --- |

| [DataDog profiler](https://docs.datadoghq.com/tracing/profiler/getting_started/?tab=python) | Yes | Yes | Yes | No |  |

| [Py-Spy](https://github.com/benfred/py-spy) | Yes | No | No | Yes | Yes |

| [Austin](https://github.com/P403n1x87/austin) | Yes | No | No | Yes | No |

Documentation[¶](#documentation "Permalink to this headline")

-------------------------------------------------------------

### Usage[¶](#usage "Permalink to this headline")

#### Installation[¶](#installation "Permalink to this headline")

Gauge can be installed as a regular Python package. Currently, it is not

published on PyPI so you have to clone [the repository](https://github.com/AndreiPashkin/gauge/) to install it.

##### Prerequisites[¶](#prerequisites "Permalink to this headline")

* [CMake](https://cmake.org/) above 3.14.

* Some sort of C++ 14 compatible compiler.

* CPython 3.5+.

* CPython’s headers.

On recent Debian/Ubuntu version you would be able to install everything

necessary with similar commands:

```

sudo apt-get update

sudo apt-get install build-essential cmake python3.8 python3.8-dev

```

These exact commands work on Ubuntu 18.04 for example.

##### Installation steps[¶](#installation-steps "Permalink to this headline")

1. Clone the project from [the GitHub repo](https://github.com/AndreiPashkin/gauge/).

2. Execute `python setup.py install`.

Warning

The project doesn’t store C++ dependency libraries in the

repository like some others do, instead - it downloads them on

demand.

Downloading can take some time so don’t be surprised to find

yourself waiting a little bit during installation.

That’s it.

#### Quickstart[¶](#quickstart "Permalink to this headline")

Gauge built on three types of entities - collectors, aggregators, exporters.

Collectors - collect raw data about execution, aggregators - aggregate them,

exporters - push them to somewhere (monitor software).

To instantiate the profiler implementations of these entities has to be

combined.

##### Minimal example[¶](#minimal-example "Permalink to this headline")

```

import gauge

from elasticapm import Client

from elasticapm.contrib.opentracing import Tracer

client = Client({

    'SERVICE\_NAME': 'my-service',

})

tracer = Tracer(client\_instance=client)

collector = gauge.SamplingCollector()

aggregator = gauge.SpanAggregator()

collector.subscribe(aggregator)

exporter = gauge.OpenTracingExporter(tracer=tracer)

aggregator.subscribe(exporter)

collector.start()

# ... work work work

collector.stop()

aggregator.finish\_open\_spans()

client.close()

```

### Development[¶](#development "Permalink to this headline")

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

project.

#### Development environment[¶](#development-environment "Permalink to this headline")

Here is how to create a local development environment:

> 

> 1. First of all install everything described in [Prerequisites](index.html#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](https://tox.readthedocs.io/en/latest/) 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[¶](#architecture-overview "Permalink to this headline")

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[¶](#commit-message-format "Permalink to this headline")

* 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[¶](#example-good-commit-message "Permalink to this headline")

```

Add foo() method into Bar class.

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

awesome.

#42, #36, #11

```

#### Contribution guide[¶](#contribution-guide "Permalink to this headline")

Nothing complex for now - just create an issue on the issue tracker or comment

on the existing one and then make a pull request ;)

Indices and tables[¶](#indices-and-tables "Permalink to this headline")

-----------------------------------------------------------------------

* [Index](genindex.html)

* [Module Index](py-modindex.html)

* [Search Page](search.html)

[Gauge](index.html#document-index)

==================================

### Navigation

Contents:

* [Introduction](index.html#document-index)

* [Usage](index.html#document-Usage)

* [Development](index.html#document-Development)

### Related Topics

* [Documentation overview](index.html#document-index)

### Quick search

 ©2020, Andrei Pashkin.

 

 |

 Powered by [Sphinx 1.8.5](http://sphinx-doc.org/)

 & [Alabaster 0.7.12](https://github.com/bitprophet/alabaster)

