Initial import of Brookhaven site

tapdown/lib/python3.11/site-packages/eventlet/zipkin/README.rst

@@ -0,0 +1,130 @@
+eventlet.zipkin
+===============
+
+`Zipkin <http://twitter.github.io/zipkin/>`_ is a distributed tracing system developed at Twitter.
+This package provides a WSGI application using eventlet
+with tracing facility that complies with Zipkin.
+
+Why use it?
+From the http://twitter.github.io/zipkin/:
+
+"Collecting traces helps developers gain deeper knowledge about how
+certain requests perform in a distributed system. Let's say we're having
+problems with user requests timing out. We can look up traced requests
+that timed out and display it in the web UI. We'll be able to quickly
+find the service responsible for adding the unexpected response time. If
+the service has been annotated adequately we can also find out where in
+that service the issue is happening."
+
+
+Screenshot
+----------
+
+Zipkin web ui screenshots obtained when applying this module to
+`OpenStack swift <https://github.com/openstack/swift>`_  are in example/.
+
+
+Requirement
+-----------
+
+A eventlet.zipkin needs `python scribe client <https://pypi.python.org/pypi/facebook-scribe/>`_
+and `thrift <https://thrift.apache.org/>`_ (>=0.9),
+because the zipkin collector speaks `scribe <https://github.com/facebookarchive/scribe>`_ protocol.
+Below command will install both scribe client and thrift.
+
+Install facebook-scribe:
+
+::
+
+    pip install facebook-scribe
+
+**Python**: ``2.7`` (Because the current Python Thrift release doesn't support Python 3)
+
+
+How to use
+----------
+
+Add tracing facility to your application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Apply the monkey patch before you start wsgi server.
+
+.. code:: python
+
+    # Add only 2 lines to your code
+    from eventlet.zipkin import patcher
+    patcher.enable_trace_patch()
+
+    # existing code
+    from eventlet import wsgi
+    wsgi.server(sock, app)
+
+You can pass some parameters to ``enable_trace_patch()``
+
+* host: Scribe daemon IP address (default: '127.0.0.1')
+* port: Scribe daemon port (default: 9410)
+* 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)
+* 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)
+
+
+(Option) Annotation API
+~~~~~~~~~~~~~~~~~~~~~~~
+If you want to record additional information,
+you can use below API from anywhere in your code.
+
+.. code:: python
+
+   from eventlet.zipkin import api
+
+   api.put_annotation('Cache miss for %s' % request)
+   api.put_key_value('key', 'value')
+
+
+
+
+Zipkin simple setup
+-------------------
+
+::
+
+    $ git clone https://github.com/twitter/zipkin.git
+    $ cd zipkin
+    # Open 3 terminals
+    (terminal1) $ bin/collector
+    (terminal2) $ bin/query
+    (terminal3) $ bin/web
+
+Access http://localhost:8080 from your browser.
+
+
+(Option) fluentd
+----------------
+If you want to buffer the tracing data for performance,
+`fluentd scribe plugin <http://docs.fluentd.org/articles/in_scribe>`_ is available.
+Since ``out_scribe plugin`` extends `Buffer Plugin <http://docs.fluentd.org/articles/buffer-plugin-overview>`_ ,
+you can customize buffering parameters in the manner of fluentd.
+Scribe plugin is included in td-agent by default.
+
+
+Sample: ``/etc/td-agent/td-agent.conf``
+
+::
+
+   # in_scribe
+   <source>
+     type scribe
+     port 9999
+   </source>
+
+   # out_scribe
+   <match zipkin.**>
+     type scribe
+     host Zipkin_collector_IP
+     port 9410
+     flush_interval 60s
+     buffer_chunk_limit 256m
+   </match>
+
+| And, you need to specify ``patcher.enable_trace_patch(port=9999)`` for in_scribe.
+| In this case, trace data is passed like below.
+| Your application => Local fluentd in_scribe (9999) => Local fluentd out_scribe <buffering> =====> Remote zipkin collector (9410)
+