{ "info": { "author": "Shane Hathaway", "author_email": "shane@hathawaymix.org", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: Repoze Public License", "Programming Language :: Python :: 2", "Programming Language :: Python :: 3", "Topic :: System :: Monitoring" ], "description": "Introduction\n============\n\nThe perfmetrics package provides a simple way to add software performance\nmetrics to Python libraries and applications. Use perfmetrics to find the\ntrue bottlenecks in a production application.\n\nThe perfmetrics package is a client of the Statsd daemon by Etsy, which\nis in turn a client of Graphite (specifically, the Carbon daemon). Because\nthe perfmetrics package sends UDP packets to Statsd, perfmetrics adds\nno I/O delays to applications and little CPU overhead. It can work\nequally well in threaded (synchronous) or event-driven (asynchronous)\nsoftware.\n\n|TravisBadge|_\n\n.. |TravisBadge| image:: https://secure.travis-ci.org/hathawsh/perfmetrics.png?branch=master\n.. _TravisBadge: http://travis-ci.org/hathawsh/perfmetrics\n\n\nUsage\n=====\n\nUse the ``@metric`` and ``@metricmethod`` decorators to wrap functions\nand methods that should send timing and call statistics to Statsd.\nAdd the decorators to any function or method that could be a bottleneck,\nincluding library functions.\n\nSample::\n\n from perfmetrics import metric\n from perfmetrics import metricmethod\n\n @metric\n def myfunction():\n \"\"\"Do something that might be expensive\"\"\"\n\n class MyClass(object):\n \t@metricmethod\n \tdef mymethod(self):\n \t \"\"\"Do some other possibly expensive thing\"\"\"\n\nNext, tell perfmetrics how to connect to Statsd. (Until you do, the\ndecorators have no effect.) Ideally, either your application should read the\nStatsd URI from a configuration file at startup time, or you should set\nthe STATSD_URI environment variable. The example below uses a\nhard-coded URI::\n\n from perfmetrics import set_statsd_client\n set_statsd_client('statsd://localhost:8125')\n\n for i in xrange(1000):\n myfunction()\n MyClass().mymethod()\n\nIf you run that code, it will fire 2000 UDP packets at port\n8125. However, unless you have already installed Graphite and Statsd,\nall of those packets will be ignored and dropped. Dropping is a good thing:\nyou don't want your production application to fail or slow down just\nbecause your performance monitoring system is stopped or not working.\n\nInstall Graphite and Statsd to receive and graph the metrics. One good way\nto install them is the `graphite_buildout example`_ at github, which\ninstalls Graphite and Statsd in a custom location without root access.\n\n.. _`graphite_buildout example`: https://github.com/hathawsh/graphite_buildout\n\n\nPyramid and WSGI\n================\n\nIf you have a Pyramid app, you can set the ``statsd_uri`` for each\nrequest by including perfmetrics in your configuration::\n\n config = Configuration(...)\n config.include('perfmetrics')\n\nAlso add a ``statsd_uri`` setting such as ``statsd://localhost:8125``.\nOnce configured, the perfmetrics tween will set up a Statsd client for\nthe duration of each request. This is especially useful if you run\nmultiple apps in one Python interpreter and you want a different\n``statsd_uri`` for each app.\n\nSimilar functionality exists for WSGI apps. Add the app to your Paste Deploy\npipeline::\n\n [statsd]\n use = egg:perfmetrics#statsd\n statsd_uri = statsd://localhost:8125\n\n [pipeline:main]\n pipeline =\n statsd\n egg:myapp#myentrypoint\n\n\nThreading\n=========\n\nWhile most programs send metrics from any thread to a single global\nStatsd server, some programs need to use a different Statsd server\nfor each thread. If you only need a global Statsd server, use the\n``set_statsd_client`` function at application startup. If you need\nto use a different Statsd server for each thread, use the\n``statsd_client_stack`` object in each thread. Use the\n``push``, ``pop``, and ``clear`` methods.\n\n\nGraphite Tips\n=============\n\nGraphite stores each metric as a time series with multiple\nresolutions. The sample graphite_buildout stores 10 second resolution\nfor 48 hours, 1 hour resolution for 31 days, and 1 day resolution for 5 years.\nTo produce a coarse grained value from a fine grained value, Graphite computes\nthe mean value (average) for each time span.\n\nBecause Graphite computes mean values implicitly, the most sensible way to\ntreat counters in Graphite is as a \"hits per second\" value. That way,\na graph can produce correct results no matter which resolution level\nit uses.\n\nTreating counters as hits per second has unfortunate consequences, however.\nIf some metric sees a 1000 hit spike in one second, then falls to zero for\nat least 9 seconds, the Graphite chart for that metric will show a spike\nof 100, not 1000, since Graphite receives metrics every 10 seconds and the\nspike looks to Graphite like 100 hits per second over a 10 second period.\n\nIf you want your graph to show 1000 hits rather than 100 hits per second,\napply the Graphite ``hitcount()`` function, using a resolution of\n10 seconds or more. The hitcount function converts per-second\nvalues to approximate raw hit counts. Be sure\nto provide a resolution value large enough to be represented by at least\none pixel width on the resulting graph, otherwise Graphite will compute\naverages of hit counts and produce a confusing graph.\n\nIt usually makes sense to treat null values in Graphite as zero, though\nthat is not the default; by default, Graphite draws nothing for null values.\nYou can turn on that option for each graph.\n\n\nReference Documentation\n=======================\n\nDecorators\n----------\n\n@metric\n Notifies Statsd using UDP every time the function is called.\n Sends both call counts and timing information. The name of the metric\n sent to Statsd is ``.``.\n\n@metricmethod\n Like ``@metric``, but the name of the Statsd metric is\n ``..``.\n\nMetric(stat=None, rate=1, method=False, count=True, timing=True)\n A decorator or context manager with options.\n\n ``stat`` is the name of the metric to send; set it to None to use\n the name of the function or method.\n ``rate`` lets you reduce the number of packets sent to Statsd\n by selecting a random sample; for example, set it to 0.1 to send\n one tenth of the packets.\n If the ``method`` parameter is true, the default metric name is based on\n the method's class name rather than the module name.\n Setting ``count`` to False disables the counter statistics sent to Statsd.\n Setting ``timing`` to False disables the timing statistics sent to Statsd.\n\n Sample use as a decorator::\n\n @Metric('frequent_func', rate=0.1, timing=False)\n def frequent_func():\n \"\"\"Do something fast and frequently\"\"\"\n\n Sample use as a context manager::\n\n def do_something():\n with Metric('doing_something'):\n pass\n\n If perfmetrics sends packets too frequently, UDP packets may be lost\n and the application performance may be affected. You can reduce\n the number of packets and the CPU overhead using the ``Metric``\n decorator with options instead of ``metric`` or ``metricmethod``.\n The decorator example above uses a sample rate and a static metric name.\n It also disables the collection of timing information.\n\n When using Metric as a context manager, you must provide the\n ``stat`` parameter or nothing will be recorded.\n\n\nFunctions\n---------\n\nstatsd_client()\n Return the currently configured ``StatsdClient``.\n Returns the thread-local client if there is one, or the global client\n if there is one, or None.\n\nset_statsd_client(client_or_uri)\n Set the global ``StatsdClient``. The\n ``client_or_uri`` can be a StatsdClient, a ``statsd://`` URI, or None.\n Note that when the perfmetrics module is imported, it looks for the\n ``STATSD_URI`` environment variable and calls set_statsd_client()\n if that variable is found.\n\nstatsd_client_from_uri(uri)\n Create a ``StatsdClient`` from a URI, but do not install it as the\n global StatsdClient.\n A typical URI is ``statsd://localhost:8125``. Supported optional\n query parameters are ``prefix`` and ``gauge_suffix``. The default\n prefix is empty and the default gauge_suffix\n is ``.``. See the ``StatsdClient`` documentation for\n more information about ``gauge_suffix``.\n\n\nStatsdClient Methods\n--------------------\n\nPython code can send custom metrics by first getting the current\n``StatsdClient`` using the ``statsd_client()`` function. Note that\n``statsd_client()`` returns None if no client has been configured.\n\nMost of the methods below have optional ``rate``, ``rate_applied``,\nand ``buf`` parameters. The ``rate`` parameter, when set to a value\nless than 1, causes StatsdClient to send a random sample of packets rather\nthan every packet. The ``rate_applied`` parameter, if true, informs\n``StatsdClient`` that the sample rate has already been applied and the\npacket should be sent regardless of the specified sample rate.\n\nIf the ``buf`` parameter is a list, StatsdClient\nappends the packet contents to the ``buf`` list rather than send the\npacket, making it possible to send multiple updates in a single packet.\nKeep in mind that the size of UDP packets is limited (the limit varies\nby the network, but 1000 bytes is usually a good guess) and any extra\nbytes will be ignored silently.\n\ntiming(stat, value, rate=1, buf=None, rate_applied=False)\n Record timing information.\n ``stat`` is the name of the metric to record and ``value`` is the\n timing measurement in milliseconds. Note that\n Statsd maintains several data points for each timing metric, so timing\n metrics can take more disk space than counters or gauges.\n\ngauge(stat, value, suffix=None, rate=1, buf=None, rate_applied=False)\n Update a gauge value.\n ``stat`` is the name of the metric to record and ``value`` is the new\n gauge value. A gauge represents a persistent value such as a pool size.\n Because gauges from different machines often conflict, a\n suffix is usually applied to gauge names. If the ``suffix``\n parameter is a string (including an empty string), it overrides the\n default gauge suffix.\n\nincr(stat, count=1, rate=1, buf=None, rate_applied=False)\n Increment a counter by ``count``. Note that Statsd clears all counter\n values every time it sends the metrics to Graphite, which usually\n happens every 10 seconds. If you need a persistent value, it may\n be more appropriate to use a gauge instead of a counter.\n\ndecr(stat, count=1, rate=1, buf=None, rate_applied=False)\n Decrement a counter by ``count``.\n\nsendbuf(buf)\n Send the contents of the ``buf`` list to Statsd.\n\n\n\nCHANGES\n=======\n\n2.3 (2015-10-22)\n\n- Add MANIFEST file\n\n2.2 (2015-10-22)\n----------------\n\n- Update CHANGES\n\n2.1 (2015-10-22)\n----------------\n\n- Detect if decorated method is class method or object method and behave\n accordingly.\n\n2.0 (2013-12-10)\n----------------\n\n- Added the @MetricMod decorator, which changes the name of metrics in\n a given context. For example, \"@MetricMod('xyz.%s')\" adds a prefix.\n\n- Removed the \"gauge suffix\" feature. It was unnecessarily confusing.\n\n- Timing metrics produced by \"@metric\", \"@metricmethod\", and \"@Metric\"\n now have a \".t\" suffix by default to avoid naming conflicts.\n\n1.0 (2012-10-09)\n----------------\n\n- Added 'perfmetrics.tween' and 'perfmetrics.wsgi' stats for measuring\n request timing and counts.\n\n0.9.5 (2012-09-22)\n------------------\n\n- Added an optional Pyramid tween and a similar WSGI filter app\n that sets up the Statsd client for each request.\n\n0.9.4 (2012-09-08)\n------------------\n\n- Optimized the use of reduced sample rates.\n\n0.9.3 (2012-09-08)\n------------------\n\n- Support the STATSD_URI environment variable.\n\n0.9.2 (2012-09-01)\n------------------\n\n- Metric can now be used as either a decorator or a context manager.\n\n- Made the signature of StatsdClient more like James Socol's StatsClient.\n\n0.9.1 (2012-09-01)\n------------------\n\n- Fixed package metadata.\n\n0.9 (2012-08-31)\n----------------\n\n- Initial release.", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/NetAccessCorp/perfmetrics", "keywords": null, "license": "BSD-derived (http://www.repoze.org/LICENSE.txt)", "maintainer": null, "maintainer_email": null, "name": "netaccess_perfmetrics", "package_url": "https://pypi.org/project/netaccess_perfmetrics/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/netaccess_perfmetrics/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/NetAccessCorp/perfmetrics" }, "release_url": "https://pypi.org/project/netaccess_perfmetrics/2.3/", "requires_dist": null, "requires_python": null, "summary": "Send performance metrics about Python code to Statsd", "version": "2.3" }, "last_serial": 1780935, "releases": { "2.1": [], "2.2": [ { "comment_text": "", "digests": { "md5": "ab4bdc8af23a14c015cdfb37ac28f3b0", "sha256": "57eb35af3c38ee5588fb089f7accb2f1f5d468fec82faf5e4b0fb6c1e040213e" }, "downloads": -1, "filename": "netaccess_perfmetrics-2.2.tar.gz", "has_sig": false, "md5_digest": "ab4bdc8af23a14c015cdfb37ac28f3b0", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 16005, "upload_time": "2015-10-22T05:00:18", "url": "https://files.pythonhosted.org/packages/6a/a8/6ad9273a54f3a0834cdc8d712147e713b55ed13130aa7ef7aeff77698bc8/netaccess_perfmetrics-2.2.tar.gz" } ], "2.3": [ { "comment_text": "", "digests": { "md5": "596cbd034b802e80cfc0be2c306b2b56", "sha256": "25e15d7e586d7f504e79e0af9323082dbed692ddc84838ef7739e81bb282ec53" }, "downloads": -1, "filename": "netaccess_perfmetrics-2.3.tar.gz", "has_sig": false, "md5_digest": "596cbd034b802e80cfc0be2c306b2b56", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 16730, "upload_time": "2015-10-22T05:29:54", "url": "https://files.pythonhosted.org/packages/fa/b9/01d1c9367ebf39f487fd2aa6acf6006ca30ead8934eb83bc0a819b75d022/netaccess_perfmetrics-2.3.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "596cbd034b802e80cfc0be2c306b2b56", "sha256": "25e15d7e586d7f504e79e0af9323082dbed692ddc84838ef7739e81bb282ec53" }, "downloads": -1, "filename": "netaccess_perfmetrics-2.3.tar.gz", "has_sig": false, "md5_digest": "596cbd034b802e80cfc0be2c306b2b56", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 16730, "upload_time": "2015-10-22T05:29:54", "url": "https://files.pythonhosted.org/packages/fa/b9/01d1c9367ebf39f487fd2aa6acf6006ca30ead8934eb83bc0a819b75d022/netaccess_perfmetrics-2.3.tar.gz" } ] }