Pyformance

0.4 · abandoned · verified Thu Apr 16

Pyformance is a Python library for performance metrics, inspired by Coda Hale's Yammer metrics (now Dropwizard Metrics). It provides various metric types like Counters, Timers, Gauges, and Histograms, along with different reporters (e.g., Console, Graphite). The current version is 0.4, released in 2016. The project is no longer actively maintained.

Common errors

```
AttributeError: module 'pyformance' has no attribute 'MetricRegistry'
```
cause Attempting to import MetricRegistry directly from the top-level 'pyformance' package.

fix Import MetricRegistry from its specific submodule: `from pyformance.registry import MetricRegistry`.
```
AttributeError: module 'pyformance' has no attribute 'Counter'
```
cause Attempting to import metric types (Counter, Timer, Gauge) directly from the top-level 'pyformance' package.

fix Import metric types from the 'meters' submodule: `from pyformance.meters import Counter` (or Timer, Gauge).
```
TypeError: Cannot create a new metric 'app.gauge.value' with type <class 'pyformance.meters.Counter'>. A metric with type <class 'pyformance.meters.Gauge'> already exists and types are different.
```
cause Trying to register a metric name with `get_or_create_metric` but providing a different metric type than one already registered under that name.

fix Ensure you are using the correct metric type when calling `get_or_create_metric`. If a metric name needs to change type, it's best to use a new, unique name or clear and reinitialize the registry.

Warnings

breaking Pyformance is not actively maintained since 2016. It may not be compatible with newer Python versions (3.8+) and will not receive security updates or bug fixes. Consider more modern alternatives for new projects.
Fix: For new projects, evaluate actively maintained libraries like `prometheus_client` or `opentelemetry` for robust metrics and monitoring solutions.
gotcha The library explicitly requires Python >=2.7 and !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*. While it supports Python 3.4+, compatibility with very recent Python versions (3.8+) is not guaranteed due to lack of testing and maintenance.
Fix: If encountering issues on newer Python versions, try running in a Python 3.4-3.7 environment or migrate to a different metrics library. Check your `python_requires` setting if packaging.
gotcha When creating a Gauge, you must subclass `pyformance.meters.Gauge` and implement the `get_value` method to return the current metric value. Unlike Counters or Timers, Gauges are not updated directly but rather poll their value.
Fix: Define a custom class inheriting from `meters.Gauge` and override `get_value()`. Then, use `metrics.add_metric('metric.name', MyCustomGauge())` to register it.

Install

pip install pyformance Install Pyformance

Imports

MetricRegistry
wrong:
```
from pyformance import MetricRegistry
```
correct:
```
from pyformance.registry import MetricRegistry
```
MetricRegistry is located in the 'registry' submodule, not directly under the top-level package.
Counter
wrong:
```
from pyformance import Counter
```
correct:
```
from pyformance.meters import Counter
```
Metric types like Counter, Timer, and Gauge are found within the 'meters' submodule.
Timer
wrong:
```
from pyformance import Timer
```
correct:
```
from pyformance.meters import Timer
```
Metric types like Counter, Timer, and Gauge are found within the 'meters' submodule.
Gauge
wrong:
```
from pyformance import Gauge
```
correct:
```
from pyformance.meters import Gauge
```
Metric types like Counter, Timer, and Gauge are found within the 'meters' submodule.

Quickstart

This quickstart demonstrates how to initialize a MetricRegistry, create and interact with common metric types (Counter, Timer, Gauge), and report their values using the ConsoleReporter.

import time
from pyformance import registry, meters, reporters

# 1. Initialize a MetricRegistry
metrics = registry.MetricRegistry()

# 2. Create and use a Counter
request_counter = metrics.get_or_create_metric('app.requests.total', meters.Counter)
request_counter.inc() # Increment by 1
request_counter.inc(5) # Increment by 5

# 3. Create and use a Timer
processing_timer = metrics.get_or_create_metric('app.processing_time', meters.Timer)
with processing_timer.time():
    time.sleep(0.05) # Simulate some work

# 4. Create and use a Gauge (custom implementation for dynamic values)
class QueueSizeGauge(meters.Gauge):
    def __init__(self, queue_list):
        super().__init__()
        self._queue_list = queue_list
    def get_value(self):
        return len(self._queue_list)

my_queue_data = [1, 2, 3, 4, 5]
metrics.add_metric('app.queue.size', QueueSizeGauge(my_queue_data))

# 5. Report metrics (e.g., to console)
console_reporter = reporters.ConsoleReporter()
console_reporter.add_metric_registry(metrics)
print("\n--- Pyformance Metrics Report ---")
console_reporter.report()
print("---------------------------------")

view raw JSON →