spotify/shumway

Name: shumway

Owner: Spotify

Description: A micro metrics framework for FFWD

Created: 2017-11-20 20:47:26.0

Updated: 2017-11-20 22:24:01.0

Pushed: 2017-11-20 22:21:50.0

Homepage: null

Size: 13

Language: Python

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

shumway

A micro library for sending metrics to a FFWD agent.

Requirements

• Either Python 2.7 or 3.6. Tests pass on Python 3.4, 3.5, and PyPy 5.8 (2.7.13).
• Support for Linux & OS X

To Use

) $ pip install shumway

Counters

Create a default counter and send to FFWD:

rt shumway

 shumway.MetricRelay(SERVICE_NAME)
ncr(METRIC_NAME)
lush()

Initialize a counter with a value

rt shumway

 shumway.MetricRelay(SERVICE_NAME)
ter = shumway.Counter(metric_name, SERVICE_NAME, value=10)
et_counter(metric_name, counter)
ncr(metric_name)
lush()

Different increment values

Create a named counter and increment by a value different than 1:

rt shumway

 shumway.MetricRelay(SERVICE_NAME)
ncr(METRIC_NAME, 2)
lush()

Custom Counter Attributes

Set custom attributes for metrics:

rt shumway

 shumway.MetricRelay(SERVICE_NAME)
ter = shumway.counter(metric_name, SERVICE_NAME,
                      {attr_1: value_1,
                       attr_2: value_2})

et_counter(metric_name, counter)
ncr(metric_name)
lush()

NB: If you use duplicate names when calling set_counter it will overwrite the counter. You will likely want to use a unique metric name for each set of attributes you are setting.

Timers

rt shumway

 shumway.MetricRelay(SERVICE_NAME)
r = mr.timer('timing-this-thing')

 timer:
...task you want to time

lush()

Custom Timer Attributes

Timers can also be created independently in order to set custom attributes:

rt shumway

 shumway.MetricRelay(SERVICE_NAME)
r = shumway.Timer('timing-this-thing', SERVICE_NAME,
                  {'attr_1': value_1, 'attr_2': value_2})

 timer:
# ...task you want to time

et_timer('timing-this-thing', timer)
lush()

Sending Metrics

There are two ways to send metrics to the ffwd agent:

Emit one metric

You can emit a one-off, event-type metric immediately:

rt shumway

 shumway.MetricRelay('my-service')

me event happened
mit('a-successful-event', 1)

me event happened with attributes
mit('a-successful-event', 1, {'attr_1': value_1, 'attr_2': value_2})

 event with a multiple value happened
mit('a-successful-event', 5)

Flushing all metrics

For batch-like metrics, you can flush metrics once you're ready:

rt shumway

 shumway.MetricRelay('my-service')

asure all the things
me all the things

ot dry_run:
mr.flush()

Existing Metrics

Check for existence of metrics in the MetricRelay with in:

import shumway
mr = shumway.MetricRelay('my-service')
counter = shumway.Counter('thing-to-count', 'my-service', value=5)
mr.set_counter('thing-to-count', counter)
'thing-to-count' in mr

'not-a-counter' in mr
e

Custom FFWD agents

By default, shumway will send metrics to a local ffwd agent at 127.0.0.1:19000.

If your ffwd agent is elsewhere, then pass that information through when initializing the MetricRelay:

rt shumway

 shumway.MetricRelay(SERVICE_NAME, ffwd_ip='10.99.0.1', ffwd_port=19001)

 the thing

Developer Setup

For development and running tests, your system must have all supported versions of Python installed. We suggest using pyenv.

Setup

t clone git@github.com:spotify/shumway.git && cd shumway
ke a virtualenv
) $ pip install -r dev-requirements.txt

Running tests

To run the entire test suite:

tside of the virtualenv
 tox is not yet installed
p install tox
x

If you want to run the test suite for a specific version of Python:

tside of the virtualenv
x -e py27
x -e py36

To run an individual test, call nosetests directly:

side virtualenv
) $ nosetests test/metrics_test.py

Code of Conduct

This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.