shumway

一个用于向 FFWD 代理发送指标的小型库。

需求

• Python 3.7。在 3.7、3.8 和最新 PyPy3 编译时测试通过。
• 支持 Linux 和 OS X

使用方法

(env) $ pip install shumway

计数器

创建一个默认计数器并发送到 FFWD

import shumway

mr = shumway.MetricRelay(SERVICE_NAME)
mr.incr(METRIC_NAME)
mr.flush()

使用一个值初始化计数器

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()

不同的增加值

创建一个命名计数器并按不同于 1 的值增加

import shumway

mr = shumway.MetricRelay(SERVICE_NAME)
mr.incr(METRIC_NAME, 2)
mr.flush()

自定义计数器属性

为指标设置自定义属性

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()

注意：如果您在调用 set_counter 时使用重复的名称，它将覆盖计数器。您可能希望为每组设置的属性使用唯一的指标名称。

计时器

import shumway

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

with timer:
    ...task you want to time

mr.flush()

自定义计时器属性

计时器也可以独立创建，以便设置自定义属性

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()

与指标对象交互

指标对象（如计时器）本身也有一个 flush 函数以及一个 as_dict 函数

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())

非自定义指标默认属性

指标中继也可以创建具有常见属性的指标

import shumway

attributes = dict(foo='bar')
mr = shumway.MetricRelay(SERVICE_NAME, default_attributes=attributes)

资源标识符

指标中继还可以发送资源标识符

import shumway

resources = dict(podname='my_ephemeral_podname')
mr = shumway.MetricRelay(SERVICE_NAME, default_resources=resources)

有关资源标识符的更多信息，请参阅 Heroic 文档

发送指标

有两种方式可以将指标发送到 ffwd 代理

发出一个指标

您可以立即发出一个一次性的事件类型指标

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)

刷新所有指标

对于批量类型的指标，您可以在准备好后刷新指标

import shumway

mr = shumway.MetricRelay('my-service')

# measure all the things
# time all the things

if not dry_run:
    mr.flush()

现有指标

使用 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
True
>>> 'not-a-counter' in mr
False

自定义 FFWD 代理

默认情况下，shumway 将指标发送到本地 ffwd 代理，地址为 127.0.0.1:19000。

如果您的 ffwd 代理在其他位置，则在初始化 MetricRelay 时传递该信息

import shumway

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

# do the thing

通过 HTTP 向 FFWD 发送指标

除了通过 UDP，也可以通过设置 use_http 标志通过 HTTP 发送指标

import shumway

mr = shumway.MetricRelay(SERVICE_NAME,
                         ffwd_host="http://my-metrics-api.com",
                         ffwd_port=8080,
                         ffwd_path="/v1/metrics",
                         use_http=True)

ffwd_host 参数应该是 HTTP 端点，并且可选地可以设置 ffwd_path 以指定路径。

变更

未发布

4.0.0

• 删除 python3.6 并使用 python3.7 作为最低要求版本

3.0.0 - 3.0.2

• 由于依赖项更新和支持 Python 版本的变化，进行了主要版本升级。

2.0.0

• 对于 Meter()、Counter()、Timer() 和 MetricRelay(...).emit() 的位置参数进行了更改，以添加 resources。如果您只使用命名参数，则这应该不会有问题。

开发者设置

为了开发和运行测试，您的系统必须安装所有支持的 Python 版本。我们建议使用 pyenv。

设置

$ git clone git@github.com:spotify/shumway.git && cd shumway
# make a virtualenv
(env) $ pip install -r dev-requirements.txt

运行测试

要运行整个测试套件

# outside of the virtualenv
# if tox is not yet installed
$ pip install tox
$ tox

如果您想为特定的 Python 版本运行测试套件

# outside of the virtualenv
$ tox -e py37

要运行单个测试，请直接调用 nosetests

# inside virtualenv
(env) $ nosetests test/metrics_test.py

行为准则

本项目遵守 开源行为准则。通过参与，您应遵守此准则。