codekingpro/portable-devtools

1eventlet.zipkin2===============3 4`Zipkin <http://twitter.github.io/zipkin/>`_ is a distributed tracing system developed at Twitter.5This package provides a WSGI application using eventlet6with tracing facility that complies with Zipkin.7 8Why use it?9From the http://twitter.github.io/zipkin/:10 11"Collecting traces helps developers gain deeper knowledge about how12certain requests perform in a distributed system. Let's say we're having13problems with user requests timing out. We can look up traced requests14that timed out and display it in the web UI. We'll be able to quickly15find the service responsible for adding the unexpected response time. If16the service has been annotated adequately we can also find out where in17that service the issue is happening."18 19 20Screenshot21----------22 23Zipkin web ui screenshots obtained when applying this module to24`OpenStack swift <https://github.com/openstack/swift>`_  are in example/.25 26 27Requirement28-----------29 30A eventlet.zipkin needs `python scribe client <https://pypi.python.org/pypi/facebook-scribe/>`_31and `thrift <https://thrift.apache.org/>`_ (>=0.9),32because the zipkin collector speaks `scribe <https://github.com/facebookarchive/scribe>`_ protocol.33Below command will install both scribe client and thrift.34 35Install facebook-scribe:36 37::38 39    pip install facebook-scribe40 41**Python**: ``2.7`` (Because the current Python Thrift release doesn't support Python 3)42 43 44How to use45----------46 47Add tracing facility to your application48~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~49Apply the monkey patch before you start wsgi server.50 51.. code:: python52 53    # Add only 2 lines to your code54    from eventlet.zipkin import patcher55    patcher.enable_trace_patch()56 57    # existing code58    from eventlet import wsgi59    wsgi.server(sock, app)60 61You can pass some parameters to ``enable_trace_patch()``62 63* host: Scribe daemon IP address (default: '127.0.0.1')64* port: Scribe daemon port (default: 9410)65* trace_app_log: A Boolean indicating if the tracer will trace application log together or not. This facility assume that your application uses python standard logging library. (default: False)66* sampling_rate: A Float value (0.0~1.0) that indicates the tracing frequency. If you specify 1.0, all requests are traced and sent to Zipkin collecotr. If you specify 0.1, only 1/10 requests are traced. (defult: 1.0)67 68 69(Option) Annotation API70~~~~~~~~~~~~~~~~~~~~~~~71If you want to record additional information,72you can use below API from anywhere in your code.73 74.. code:: python75 76   from eventlet.zipkin import api77 78   api.put_annotation('Cache miss for %s' % request)79   api.put_key_value('key', 'value')80 81 82 83 84Zipkin simple setup85-------------------86 87::88 89    $ git clone https://github.com/twitter/zipkin.git90    $ cd zipkin91    # Open 3 terminals92    (terminal1) $ bin/collector93    (terminal2) $ bin/query94    (terminal3) $ bin/web95 96Access http://localhost:8080 from your browser.97 98 99(Option) fluentd100----------------101If you want to buffer the tracing data for performance,102`fluentd scribe plugin <http://docs.fluentd.org/articles/in_scribe>`_ is available.103Since ``out_scribe plugin`` extends `Buffer Plugin <http://docs.fluentd.org/articles/buffer-plugin-overview>`_ ,104you can customize buffering parameters in the manner of fluentd.105Scribe plugin is included in td-agent by default.106 107 108Sample: ``/etc/td-agent/td-agent.conf``109 110::111 112   # in_scribe113   <source>114     type scribe115     port 9999116   </source>117 118   # out_scribe119   <match zipkin.**>120     type scribe121     host Zipkin_collector_IP122     port 9410123     flush_interval 60s124     buffer_chunk_limit 256m125   </match>126 127| And, you need to specify ``patcher.enable_trace_patch(port=9999)`` for in_scribe.128| In this case, trace data is passed like below.129| Your application => Local fluentd in_scribe (9999) => Local fluentd out_scribe <buffering> =====> Remote zipkin collector (9410)130 131