131 lines
3.8 KiB
ReStructuredText
131 lines
3.8 KiB
ReStructuredText
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)
|
|
|