# shumway
[](https://github.com/spotify/shumway/actions/workflows/main.yml) [](https://codecov.io/github/spotify/shumway)
A micro library for sending metrics to a [FFWD](https://github.com/spotify/ffwd) agent.
## Requirements
* Python 3.7. Tests pass on 3.7, and 3.8, and on the latest PyPy3 at build-time.
* Support for Linux & OS X
## To Use
```sh
(env) $ pip install shumway
```
### Counters
Create a default counter and send to FFWD:
```python
import shumway
mr = shumway.MetricRelay(SERVICE_NAME)
mr.incr(METRIC_NAME)
mr.flush()
```
#### Initialize a counter with a value
```python
import shumway
mr = shumway.MetricRelay(SERVICE_NAME)
counter = shumway.Counter(metric_name, SERVICE_NAME, value=10)
mr.set_counter(metric_name, counter)
mr.incr(metric_name)
mr.flush()
```
#### Different increment values
Create a named counter and increment by a value different than 1:
```python
import shumway
mr = shumway.MetricRelay(SERVICE_NAME)
mr.incr(METRIC_NAME, 2)
mr.flush()
```
#### Custom Counter Attributes
Set custom attributes for metrics:
```python
import shumway
mr = shumway.MetricRelay(SERVICE_NAME)
counter = shumway.counter(metric_name, SERVICE_NAME,
{attr_1: value_1,
attr_2: value_2})
mr.set_counter(metric_name, counter)
mr.incr(metric_name)
mr.flush()
```
**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
```python
import shumway
mr = shumway.MetricRelay(SERVICE_NAME)
timer = mr.timer('timing-this-thing')
with timer:
...task you want to time
mr.flush()
```
### Custom Timer Attributes
Timers can also be created independently in order to set custom attributes:
```python
import shumway
mr = shumway.MetricRelay(SERVICE_NAME)
timer = shumway.Timer('timing-this-thing', SERVICE_NAME,
{'attr_1': value_1, 'attr_2': value_2})
with timer:
# ...task you want to time
mr.set_timer('timing-this-thing', timer)
mr.flush()
```
### Interacting with metrics objects
Metric objects (like a timer) themselves have a `flush` function as well as a `as_dict` function
```python
import shumway
timer = shumway.Timer('timing-this-thing', SERVICE_NAME,
{'attr_1': value_1, 'attr_2': value_2})
timer_as_dict = timer.as_dict()
timer.flush(lambda dict: do_smth())
```
### Default attributes for non-custom metrics
MetricRelay can create metrics with a common set of attributes as well:
```python
import shumway
attributes = dict(foo='bar')
mr = shumway.MetricRelay(SERVICE_NAME, default_attributes=attributes)
```
### Resource Identifiers
MetricsRelay and send resource identifiers as well:
```python
import shumway
resources = dict(podname='my_ephemeral_podname')
mr = shumway.MetricRelay(SERVICE_NAME, default_resources=resources)
```
For more on resource identifiers see [Heroic Documentation](https://spotify.github.io/heroic/docs/data_model)
### 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:
```python
import shumway
mr = shumway.MetricRelay('my-service')
# some event happened
mr.emit('a-successful-event', 1)
# some event happened with attributes
mr.emit('a-successful-event', 1, {'attr_1': value_1, 'attr_2': value_2})
# an event with a multiple value happened
mr.emit('a-successful-event', 5)
```
#### Flushing all metrics
For batch-like metrics, you can flush metrics once you're ready:
```python
import shumway
mr = shumway.MetricRelay('my-service')
# measure all the things
# time all the things
if not dry_run:
mr.flush()
```
### Existing Metrics
Check for existence of metrics in the MetricRelay with `in`:
```pycon
>>> 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
True
>>> 'not-a-counter' in mr
False
```
### Custom FFWD agents
By default, `shumway` will send metrics to a local [`ffwd`](https://github.com/spotify/ffwd) agent at `127.0.0.1:19000`.
If your `ffwd` agent is elsewhere, then pass that information through when initializing the `MetricRelay`:
```python
import shumway
mr = shumway.MetricRelay(SERVICE_NAME, ffwd_ip='10.99.0.1', ffwd_port=19001)
# do the thing
```
### Sending Metrics via HTTP to FFWD
Instead of via UDP it is also possible to send metrics via HTTP by setting the `use_http` flag:
```python
import shumway
mr = shumway.MetricRelay(SERVICE_NAME,
ffwd_host="http://my-metrics-api.com",
ffwd_port=8080,
ffwd_path="/v1/metrics",
use_http=True)
```
The `ffwd_host` parameter should be the HTTP endpoint and optionally `ffwd_path` can be set to specify the path.
## Changes
### Unreleased
### 4.0.0
* Remove python3.6 and use python3.7 as a minimum required version
### 3.0.0 - 3.0.2
* Major version bump due to dependency updates and change to supported Python versions.
### 2.0.0
* Positional arguments for `Meter()`, `Counter()`, `Timer()`, and `MetricRelay(...).emit()` were changed to add `resources`. If using only named arguments this should not be a problem.
## Developer Setup
For development and running tests, your system must have all supported versions of Python installed. We suggest using [pyenv](https://github.com/yyuu/pyenv).
## Setup
```sh
$ git clone git@github.com:spotify/shumway.git && cd shumway
# make a virtualenv
(env) $ pip install -r dev-requirements.txt
```
## Running tests
To run the entire test suite:
```sh
# outside of the virtualenv
# if tox is not yet installed
$ pip install tox
$ tox
```
If you want to run the test suite for a specific version of Python:
```sh
# outside of the virtualenv
$ tox -e py37
```
To run an individual test, call `nosetests` directly:
```sh
# inside virtualenv
(env) $ nosetests test/metrics_test.py
```
## Code of Conduct
This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.
[code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md
Raw data
{
"_id": null,
"home_page": "https://github.com/spotify/shumway",
"name": "shumway",
"maintainer": "Lynn Root",
"docs_url": null,
"requires_python": "",
"maintainer_email": "lynn@spotify.com",
"keywords": "metrics,ffwd,heroic",
"author": "Lynn Root",
"author_email": "lynn@spotify.com",
"download_url": "https://files.pythonhosted.org/packages/41/81/b63b5b2a3170af7b77088eaf76770144afd3b0b25b223084783b1ba19538/shumway-4.0.0.tar.gz",
"platform": null,
"description": "# shumway\n\n[](https://github.com/spotify/shumway/actions/workflows/main.yml) [](https://codecov.io/github/spotify/shumway)\n\nA micro library for sending metrics to a [FFWD](https://github.com/spotify/ffwd) agent.\n\n## Requirements\n\n* Python 3.7. Tests pass on 3.7, and 3.8, and on the latest PyPy3 at build-time.\n* Support for Linux & OS X\n\n## To Use\n\n```sh\n(env) $ pip install shumway\n```\n\n### Counters\n\nCreate a default counter and send to FFWD:\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay(SERVICE_NAME)\nmr.incr(METRIC_NAME)\nmr.flush()\n```\n\n#### Initialize a counter with a value\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay(SERVICE_NAME)\ncounter = shumway.Counter(metric_name, SERVICE_NAME, value=10)\nmr.set_counter(metric_name, counter)\nmr.incr(metric_name)\nmr.flush()\n```\n\n#### Different increment values\n\nCreate a named counter and increment by a value different than 1:\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay(SERVICE_NAME)\nmr.incr(METRIC_NAME, 2)\nmr.flush()\n```\n\n#### Custom Counter Attributes\n\nSet custom attributes for metrics:\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay(SERVICE_NAME)\ncounter = shumway.counter(metric_name, SERVICE_NAME,\n {attr_1: value_1,\n attr_2: value_2})\n\nmr.set_counter(metric_name, counter)\nmr.incr(metric_name)\nmr.flush()\n\n```\n\n**NB:** If you use duplicate names when calling `set_counter` it will overwrite the\ncounter. You will likely want to use a unique metric name for each set of\nattributes you are setting.\n\n### Timers\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay(SERVICE_NAME)\ntimer = mr.timer('timing-this-thing')\n\nwith timer:\n ...task you want to time\n\nmr.flush()\n```\n\n### Custom Timer Attributes\n\nTimers can also be created independently in order to set custom attributes:\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay(SERVICE_NAME)\ntimer = shumway.Timer('timing-this-thing', SERVICE_NAME,\n {'attr_1': value_1, 'attr_2': value_2})\n\nwith timer:\n # ...task you want to time\n\nmr.set_timer('timing-this-thing', timer)\nmr.flush()\n```\n\n### Interacting with metrics objects\n\nMetric objects (like a timer) themselves have a `flush` function as well as a `as_dict` function\n\n```python\nimport shumway\n\ntimer = shumway.Timer('timing-this-thing', SERVICE_NAME,\n {'attr_1': value_1, 'attr_2': value_2})\ntimer_as_dict = timer.as_dict()\ntimer.flush(lambda dict: do_smth())\n```\n\n### Default attributes for non-custom metrics\n\nMetricRelay can create metrics with a common set of attributes as well:\n\n```python\nimport shumway\n\nattributes = dict(foo='bar')\nmr = shumway.MetricRelay(SERVICE_NAME, default_attributes=attributes)\n```\n\n### Resource Identifiers\n\nMetricsRelay and send resource identifiers as well:\n\n```python\nimport shumway\n\nresources = dict(podname='my_ephemeral_podname')\nmr = shumway.MetricRelay(SERVICE_NAME, default_resources=resources)\n```\n\nFor more on resource identifiers see [Heroic Documentation](https://spotify.github.io/heroic/docs/data_model)\n\n### Sending Metrics\n\nThere are two ways to send metrics to the `ffwd` agent:\n\n#### Emit one metric\n\nYou can emit a one-off, event-type metric immediately:\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay('my-service')\n\n# some event happened\nmr.emit('a-successful-event', 1)\n\n# some event happened with attributes\nmr.emit('a-successful-event', 1, {'attr_1': value_1, 'attr_2': value_2})\n\n# an event with a multiple value happened\nmr.emit('a-successful-event', 5)\n```\n\n#### Flushing all metrics\n\nFor batch-like metrics, you can flush metrics once you're ready:\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay('my-service')\n\n# measure all the things\n# time all the things\n\nif not dry_run:\n mr.flush()\n```\n\n### Existing Metrics\n\nCheck for existence of metrics in the MetricRelay with `in`:\n\n```pycon\n>>> import shumway\n>>> mr = shumway.MetricRelay('my-service')\n>>> counter = shumway.Counter('thing-to-count', 'my-service', value=5)\n>>> mr.set_counter('thing-to-count', counter)\n>>> 'thing-to-count' in mr\nTrue\n>>> 'not-a-counter' in mr\nFalse\n```\n\n### Custom FFWD agents\n\nBy default, `shumway` will send metrics to a local [`ffwd`](https://github.com/spotify/ffwd) agent at `127.0.0.1:19000`.\n\nIf your `ffwd` agent is elsewhere, then pass that information through when initializing the `MetricRelay`:\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay(SERVICE_NAME, ffwd_ip='10.99.0.1', ffwd_port=19001)\n\n# do the thing\n```\n\n### Sending Metrics via HTTP to FFWD\n\nInstead of via UDP it is also possible to send metrics via HTTP by setting the `use_http` flag:\n\n```python\nimport shumway\n\nmr = shumway.MetricRelay(SERVICE_NAME,\n ffwd_host=\"http://my-metrics-api.com\",\n ffwd_port=8080,\n ffwd_path=\"/v1/metrics\",\n use_http=True)\n```\n\nThe `ffwd_host` parameter should be the HTTP endpoint and optionally `ffwd_path` can be set to specify the path.\n\n## Changes\n\n### Unreleased\n\n### 4.0.0\n\n* Remove python3.6 and use python3.7 as a minimum required version\n\n### 3.0.0 - 3.0.2\n\n* Major version bump due to dependency updates and change to supported Python versions.\n\n### 2.0.0\n\n* Positional arguments for `Meter()`, `Counter()`, `Timer()`, and `MetricRelay(...).emit()` were changed to add `resources`. If using only named arguments this should not be a problem.\n\n## Developer Setup\n\nFor development and running tests, your system must have all supported versions of Python installed. We suggest using [pyenv](https://github.com/yyuu/pyenv).\n\n## Setup\n\n```sh\n$ git clone git@github.com:spotify/shumway.git && cd shumway\n# make a virtualenv\n(env) $ pip install -r dev-requirements.txt\n```\n\n## Running tests\n\nTo run the entire test suite:\n\n```sh\n# outside of the virtualenv\n# if tox is not yet installed\n$ pip install tox\n$ tox\n```\n\nIf you want to run the test suite for a specific version of Python:\n\n```sh\n# outside of the virtualenv\n$ tox -e py37\n```\n\nTo run an individual test, call `nosetests` directly:\n\n```sh\n# inside virtualenv\n(env) $ nosetests test/metrics_test.py\n```\n\n## Code of Conduct\n\nThis project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.\n\n[code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Micro metrics library for ffwd",
"version": "4.0.0",
"project_urls": {
"Homepage": "https://github.com/spotify/shumway"
},
"split_keywords": [
"metrics",
"ffwd",
"heroic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9e56f67e3f271294a267d7f0a49e5faf83eb580a72fad04d67a59d167808e71d",
"md5": "c82d2c23b454cf068a4991cd9334f99a",
"sha256": "6d4eae66baeee3fd2bc81217adb4084aa13ccf324e92ab751a9c46349cc9d4df"
},
"downloads": -1,
"filename": "shumway-4.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c82d2c23b454cf068a4991cd9334f99a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12815,
"upload_time": "2023-09-28T14:53:39",
"upload_time_iso_8601": "2023-09-28T14:53:39.427366Z",
"url": "https://files.pythonhosted.org/packages/9e/56/f67e3f271294a267d7f0a49e5faf83eb580a72fad04d67a59d167808e71d/shumway-4.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4181b63b5b2a3170af7b77088eaf76770144afd3b0b25b223084783b1ba19538",
"md5": "aa81de71c178c9eda113f663c5e95a00",
"sha256": "88963721855a8a1de28438fbe0f825e179126631303dfb3c5c331035a9936bd9"
},
"downloads": -1,
"filename": "shumway-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "aa81de71c178c9eda113f663c5e95a00",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12214,
"upload_time": "2023-09-28T14:53:40",
"upload_time_iso_8601": "2023-09-28T14:53:40.623151Z",
"url": "https://files.pythonhosted.org/packages/41/81/b63b5b2a3170af7b77088eaf76770144afd3b0b25b223084783b1ba19538/shumway-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-28 14:53:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "spotify",
"github_project": "shumway",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "shumway"
}
JSON
