Package: shumway
shumwayA micro library for sending metrics to aFFWDagent.RequirementsPython 3.7. Tests pass on 3.7, and 3.8, and on the latest PyPy3 at build-time.Support for Linux & OS XTo Use(env)$pipinstallshumwayCountersCreate a default counter and send to FFWD:importshumwaymr=shumway.MetricRelay(SERVICE_NAME)mr.incr(METRIC_NAME)mr.flush()Initialize a counter with a valueimportshumwaymr=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 valuesCreate a named counter and increment by a value different than 1:importshumwaymr=shumway.MetricRelay(SERVICE_NAME)mr.incr(METRIC_NAME,2)mr.flush()Custom Counter AttributesSet custom attributes for metrics:importshumwaymr=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 callingset_counterit will overwrite the
counter. You will likely want to use a unique metric name for each set of
attributes you are setting.Timersimportshumwaymr=shumway.MetricRelay(SERVICE_NAME)timer=mr.timer('timing-this-thing')withtimer:...taskyouwanttotimemr.flush()Custom Timer AttributesTimers can also be created independently in order to set custom attributes:importshumwaymr=shumway.MetricRelay(SERVICE_NAME)timer=shumway.Timer('timing-this-thing',SERVICE_NAME,{'attr_1':value_1,'attr_2':value_2})withtimer:# ...task you want to timemr.set_timer('timing-this-thing',timer)mr.flush()Interacting with metrics objectsMetric objects (like a timer) themselves have aflushfunction as well as aas_dictfunctionimportshumwaytimer=shumway.Timer('timing-this-thing',SERVICE_NAME,{'attr_1':value_1,'attr_2':value_2})timer_as_dict=timer.as_dict()timer.flush(lambdadict:do_smth())Default attributes for non-custom metricsMetricRelay can create metrics with a common set of attributes as well:importshumwayattributes=dict(foo='bar')mr=shumway.MetricRelay(SERVICE_NAME,default_attributes=attributes)Resource IdentifiersMetricsRelay and send resource identifiers as well:importshumwayresources=dict(podname='my_ephemeral_podname')mr=shumway.MetricRelay(SERVICE_NAME,default_resources=resources)For more on resource identifiers seeHeroic DocumentationSending MetricsThere are two ways to send metrics to theffwdagent:Emit one metricYou can emit a one-off, event-type metric immediately:importshumwaymr=shumway.MetricRelay('my-service')# some event happenedmr.emit('a-successful-event',1)# some event happened with attributesmr.emit('a-successful-event',1,{'attr_1':value_1,'attr_2':value_2})# an event with a multiple value happenedmr.emit('a-successful-event',5)Flushing all metricsFor batch-like metrics, you can flush metrics once you're ready:importshumwaymr=shumway.MetricRelay('my-service')# measure all the things# time all the thingsifnotdry_run:mr.flush()Existing MetricsCheck for existence of metrics in the MetricRelay within:>>>importshumway>>>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'inmrTrue>>>'not-a-counter'inmrFalseCustom FFWD agentsBy default,shumwaywill send metrics to a localffwdagent at127.0.0.1:19000.If yourffwdagent is elsewhere, then pass that information through when initializing theMetricRelay:importshumwaymr=shumway.MetricRelay(SERVICE_NAME,ffwd_ip='10.99.0.1',ffwd_port=19001)# do the thingSending Metrics via HTTP to FFWDInstead of via UDP it is also possible to send metrics via HTTP by setting theuse_httpflag:importshumwaymr=shumway.MetricRelay(SERVICE_NAME,ffwd_host="http://my-metrics-api.com",ffwd_port=8080,ffwd_path="/v1/metrics",use_http=True)Theffwd_hostparameter should be the HTTP endpoint and optionallyffwd_pathcan be set to specify the path.ChangesUnreleased4.0.0Remove python3.6 and use python3.7 as a minimum required version3.0.0 - 3.0.2Major version bump due to dependency updates and change to supported Python versions.2.0.0Positional arguments forMeter(),Counter(),Timer(), andMetricRelay(...).emit()were changed to addresources. If using only named arguments this should not be a problem.Developer SetupFor development and running tests, your system must have all supported versions of Python installed. We suggest usingpyenv.Setup$gitclonegit@github.com:spotify/shumway.git&&cdshumway# make a virtualenv(env)$pipinstall-rdev-requirements.txtRunning testsTo run the entire test suite:# outside of the virtualenv# if tox is not yet installed$pipinstalltox
$toxIf you want to run the test suite for a specific version of Python:# outside of the virtualenv$tox-epy37To run an individual test, callnosetestsdirectly:# inside virtualenv(env)$noseteststest/metrics_test.pyCode of ConductThis project adheres to theOpen Code of Conduct. By participating, you are expected to honor this code.