aiozipkin
=========
.. image:: https://github.com/aio-libs/aiozipkin/workflows/CI/badge.svg
:target: https://github.com/aio-libs/aiozipkin/actions?query=workflow%3ACI
.. image:: https://codecov.io/gh/aio-libs/aiozipkin/branch/master/graph/badge.svg
:target: https://codecov.io/gh/aio-libs/aiozipkin
.. image:: https://api.codeclimate.com/v1/badges/1ff813d5cad2d702cbf1/maintainability
:target: https://codeclimate.com/github/aio-libs/aiozipkin/maintainability
:alt: Maintainability
.. image:: https://img.shields.io/pypi/v/aiozipkin.svg
:target: https://pypi.python.org/pypi/aiozipkin
.. image:: https://readthedocs.org/projects/aiozipkin/badge/?version=latest
:target: http://aiozipkin.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://badges.gitter.im/Join%20Chat.svg
:target: https://gitter.im/aio-libs/Lobby
:alt: Chat on Gitter
**aiozipkin** is Python 3.6+ module that adds distributed tracing capabilities
from asyncio_ applications with zipkin (http://zipkin.io) server instrumentation.
zipkin_ is a distributed tracing system. It helps gather timing data needed
to troubleshoot latency problems in microservice architectures. It manages
both the collection and lookup of this data. Zipkin’s design is based on
the Google Dapper paper.
Applications are instrumented with **aiozipkin** report timing data to zipkin_.
The Zipkin UI also presents a Dependency diagram showing how many traced
requests went through each application. If you are troubleshooting latency
problems or errors, you can filter or sort all traces based on the
application, length of trace, annotation, or timestamp.
.. image:: https://raw.githubusercontent.com/aio-libs/aiozipkin/master/docs/zipkin_animation2.gif
:alt: zipkin ui animation
Features
========
* Distributed tracing capabilities to **asyncio** applications.
* Support zipkin_ ``v2`` protocol.
* Easy to use API.
* Explicit context handling, no thread local variables.
* Can work with jaeger_ and stackdriver_ through zipkin compatible API.
zipkin vocabulary
-----------------
Before code lets learn important zipkin_ vocabulary, for more detailed
information please visit https://zipkin.io/pages/instrumenting
.. image:: https://raw.githubusercontent.com/aio-libs/aiozipkin/master/docs/zipkin_glossary.png
:alt: zipkin ui glossary
* **Span** represents one specific method (RPC) call
* **Annotation** string data associated with a particular timestamp in span
* **Tag** - key and value associated with given span
* **Trace** - collection of spans, related to serving particular request
Simple example
--------------
.. code:: python
import asyncio
import aiozipkin as az
async def run():
# setup zipkin client
zipkin_address = 'http://127.0.0.1:9411/api/v2/spans'
endpoint = az.create_endpoint(
"simple_service", ipv4="127.0.0.1", port=8080)
tracer = await az.create(zipkin_address, endpoint, sample_rate=1.0)
# create and setup new trace
with tracer.new_trace(sampled=True) as span:
# give a name for the span
span.name("Slow SQL")
# tag with relevant information
span.tag("span_type", "root")
# indicate that this is client span
span.kind(az.CLIENT)
# make timestamp and name it with START SQL query
span.annotate("START SQL SELECT * FROM")
# imitate long SQL query
await asyncio.sleep(0.1)
# make other timestamp and name it "END SQL"
span.annotate("END SQL")
await tracer.close()
if __name__ == "__main__":
loop = asyncio.get_event_loop()
loop.run_until_complete(run())
aiohttp example
---------------
*aiozipkin* includes *aiohttp* server instrumentation, for this create
`web.Application()` as usual and install aiozipkin plugin:
.. code:: python
import aiozipkin as az
def init_app():
host, port = "127.0.0.1", 8080
app = web.Application()
endpoint = az.create_endpoint("AIOHTTP_SERVER", ipv4=host, port=port)
tracer = await az.create(zipkin_address, endpoint, sample_rate=1.0)
az.setup(app, tracer)
That is it, plugin adds middleware that tries to fetch context from headers,
and create/join new trace. Optionally on client side you can add propagation
headers in order to force tracing and to see network latency between client and
server.
.. code:: python
import aiozipkin as az
endpoint = az.create_endpoint("AIOHTTP_CLIENT")
tracer = await az.create(zipkin_address, endpoint)
with tracer.new_trace() as span:
span.kind(az.CLIENT)
headers = span.context.make_headers()
host = "http://127.0.0.1:8080/api/v1/posts/{}".format(i)
resp = await session.get(host, headers=headers)
await resp.text()
Documentation
-------------
http://aiozipkin.readthedocs.io/
Installation
------------
Installation process is simple, just::
$ pip install aiozipkin
Support of other collectors
===========================
**aiozipkin** can work with any other zipkin_ compatible service, currently we
tested it with jaeger_ and stackdriver_.
Jaeger support
--------------
jaeger_ supports zipkin_ span format as result it is possible to use *aiozipkin*
with jaeger_ server. You just need to specify *jaeger* server address and it
should work out of the box. Not need to run local zipkin server.
For more informations see tests and jaeger_ documentation.
.. image:: https://raw.githubusercontent.com/aio-libs/aiozipkin/master/docs/jaeger.png
:alt: jaeger ui animation
Stackdriver support
-------------------
Google stackdriver_ supports zipkin_ span format as result it is possible to
use *aiozipkin* with this google_ service. In order to make this work you
need to setup zipkin service locally, that will send trace to the cloud. See
google_ cloud documentation how to setup make zipkin collector:
.. image:: https://raw.githubusercontent.com/aio-libs/aiozipkin/master/docs/stackdriver.png
:alt: jaeger ui animation
Requirements
------------
* Python_ 3.6+
* aiohttp_
.. _PEP492: https://www.python.org/dev/peps/pep-0492/
.. _Python: https://www.python.org
.. _aiohttp: https://github.com/KeepSafe/aiohttp
.. _asyncio: http://docs.python.org/3.5/library/asyncio.html
.. _uvloop: https://github.com/MagicStack/uvloop
.. _zipkin: http://zipkin.io
.. _jaeger: http://jaeger.readthedocs.io/en/latest/
.. _stackdriver: https://cloud.google.com/stackdriver/
.. _google: https://cloud.google.com/trace/docs/zipkin
CHANGES
=======
..
You should *NOT* be adding new change log entries to this file, this
file is managed by towncrier. You *may* edit previous change logs to
fix problems like typo corrections or such.
To add a new change log entry, please see
https://pip.pypa.io/en/latest/development/#adding-a-news-entry
we named the news folder "changes".
WARNING: Don't drop the next directive!
.. towncrier release notes start
1.1.1 (2021-10-23)
==================
Bugfixes
--------
- Fix unhandled AssertionError in aiohttp integration when unknown resource requested by the user.
`#400 <https://github.com/aio-libs/aiozipkin/issues/400>`_
- Fix ``NoneType`` error when using ``SystemRoute``.
`#410 <https://github.com/aio-libs/aiozipkin/issues/410>`_
----
1.1.0 (2021-05-17)
==================
Bugfixes
--------
- Expect trace request context to be of SimpleNamespace type.
`#385 <https://github.com/aio-libs/aiozipkin/issues/385>`_
----
1.0.0 (2020-11-06)
==================
Bugfixes
--------
- Support Python 3.8 and Python 3.9
`#259 <https://github.com/aio-libs/aiozipkin/issues/259>`_
----
0.7.1 (2020-09-20)
==================
Bugfixes
--------
- Fix `Manifest.in` file; add `CHANGES.rst` to the Source Tarball.
0.7.0 (2020-07-17)
==================
Features
--------
- Add support of AWS X-Ray trace id format.
`#273 <https://github.com/aio-libs/aiozipkin/issues/273>`_
----
0.6.0 (2019-10-12)
------------------
* Add context var support for python3.7 aiohttp instrumentation #187
* Single header tracing support #189
* Add retries and batches to transport (thanks @konstantin-stepanov)
* Drop python3.5 support #238
* Use new typing syntax in codebase #237
0.5.0 (2018-12-25)
------------------
* More strict typing configuration is used #147
* Fixed bunch of typos in code and docs #151 #153 (thanks @deejay1)
* Added interface for Transport #155 (thanks @deejay1)
* Added create_custom helper for easer tracer configuration #160 (thanks @deejay1)
* Added interface for Sampler #160 (thanks @deejay1)
* Added py.typed marker
0.4.0 (2018-07-11)
------------------
* Add more coverage with typing #147
* Breaking change: typo send_inteval => send_interval #144 (thanks @gugu)
* Breaking change: do not append api/v2/spans to the zipkin dress #150
0.3.0 (2018-06-13)
------------------
* Add support http.route tag for aiohttp #138
* Make zipkin address builder more permissive #141 (thanks @dsantosfff)
0.2.0 (2018-03-03)
------------------
* Breaking change: az.create is coroutine now #114
* Added context manger for tracer object #114
* Added more mypy types #117
0.1.1 (2018-01-26)
------------------
* Added new_child helper method #83
0.1.0 (2018-01-21)
------------------
After few months of work and beta releases here are basic features:
* Initial release.
* Implemented zipkin v2 protocol with HTTP transport
* Added jaeger support
* Added stackdriver support
* Added aiohttp server support
* Added aiohttp 3.0.0 client tracing support
* Added examples and demos
Raw data
{
"_id": null,
"home_page": "https://github.com/aio-libs/aiozipkin",
"name": "aiozipkin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "zipkin,distributed-tracing,tracing",
"author": "Nikolay Novik",
"author_email": "nickolainovik@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f2/fe/26a60a7c9e91c968eac5dacab2948ed931a676880a6878695ff281c72b8f/aiozipkin-1.1.1.tar.gz",
"platform": "POSIX",
"description": "aiozipkin\n=========\n.. image:: https://github.com/aio-libs/aiozipkin/workflows/CI/badge.svg\n :target: https://github.com/aio-libs/aiozipkin/actions?query=workflow%3ACI\n.. image:: https://codecov.io/gh/aio-libs/aiozipkin/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/aio-libs/aiozipkin\n.. image:: https://api.codeclimate.com/v1/badges/1ff813d5cad2d702cbf1/maintainability\n :target: https://codeclimate.com/github/aio-libs/aiozipkin/maintainability\n :alt: Maintainability\n.. image:: https://img.shields.io/pypi/v/aiozipkin.svg\n :target: https://pypi.python.org/pypi/aiozipkin\n.. image:: https://readthedocs.org/projects/aiozipkin/badge/?version=latest\n :target: http://aiozipkin.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n.. image:: https://badges.gitter.im/Join%20Chat.svg\n :target: https://gitter.im/aio-libs/Lobby\n :alt: Chat on Gitter\n\n**aiozipkin** is Python 3.6+ module that adds distributed tracing capabilities\nfrom asyncio_ applications with zipkin (http://zipkin.io) server instrumentation.\n\nzipkin_ is a distributed tracing system. It helps gather timing data needed\nto troubleshoot latency problems in microservice architectures. It manages\nboth the collection and lookup of this data. Zipkin\u2019s design is based on\nthe Google Dapper paper.\n\nApplications are instrumented with **aiozipkin** report timing data to zipkin_.\nThe Zipkin UI also presents a Dependency diagram showing how many traced\nrequests went through each application. If you are troubleshooting latency\nproblems or errors, you can filter or sort all traces based on the\napplication, length of trace, annotation, or timestamp.\n\n.. image:: https://raw.githubusercontent.com/aio-libs/aiozipkin/master/docs/zipkin_animation2.gif\n :alt: zipkin ui animation\n\n\nFeatures\n========\n* Distributed tracing capabilities to **asyncio** applications.\n* Support zipkin_ ``v2`` protocol.\n* Easy to use API.\n* Explicit context handling, no thread local variables.\n* Can work with jaeger_ and stackdriver_ through zipkin compatible API.\n\n\nzipkin vocabulary\n-----------------\nBefore code lets learn important zipkin_ vocabulary, for more detailed\ninformation please visit https://zipkin.io/pages/instrumenting\n\n.. image:: https://raw.githubusercontent.com/aio-libs/aiozipkin/master/docs/zipkin_glossary.png\n :alt: zipkin ui glossary\n\n* **Span** represents one specific method (RPC) call\n* **Annotation** string data associated with a particular timestamp in span\n* **Tag** - key and value associated with given span\n* **Trace** - collection of spans, related to serving particular request\n\n\nSimple example\n--------------\n\n.. code:: python\n\n import asyncio\n import aiozipkin as az\n\n\n async def run():\n # setup zipkin client\n zipkin_address = 'http://127.0.0.1:9411/api/v2/spans'\n endpoint = az.create_endpoint(\n \"simple_service\", ipv4=\"127.0.0.1\", port=8080)\n tracer = await az.create(zipkin_address, endpoint, sample_rate=1.0)\n\n # create and setup new trace\n with tracer.new_trace(sampled=True) as span:\n # give a name for the span\n span.name(\"Slow SQL\")\n # tag with relevant information\n span.tag(\"span_type\", \"root\")\n # indicate that this is client span\n span.kind(az.CLIENT)\n # make timestamp and name it with START SQL query\n span.annotate(\"START SQL SELECT * FROM\")\n # imitate long SQL query\n await asyncio.sleep(0.1)\n # make other timestamp and name it \"END SQL\"\n span.annotate(\"END SQL\")\n\n await tracer.close()\n\n if __name__ == \"__main__\":\n loop = asyncio.get_event_loop()\n loop.run_until_complete(run())\n\n\naiohttp example\n---------------\n\n*aiozipkin* includes *aiohttp* server instrumentation, for this create\n`web.Application()` as usual and install aiozipkin plugin:\n\n\n.. code:: python\n\n import aiozipkin as az\n\n def init_app():\n host, port = \"127.0.0.1\", 8080\n app = web.Application()\n endpoint = az.create_endpoint(\"AIOHTTP_SERVER\", ipv4=host, port=port)\n tracer = await az.create(zipkin_address, endpoint, sample_rate=1.0)\n az.setup(app, tracer)\n\n\nThat is it, plugin adds middleware that tries to fetch context from headers,\nand create/join new trace. Optionally on client side you can add propagation\nheaders in order to force tracing and to see network latency between client and\nserver.\n\n.. code:: python\n\n import aiozipkin as az\n\n endpoint = az.create_endpoint(\"AIOHTTP_CLIENT\")\n tracer = await az.create(zipkin_address, endpoint)\n\n with tracer.new_trace() as span:\n span.kind(az.CLIENT)\n headers = span.context.make_headers()\n host = \"http://127.0.0.1:8080/api/v1/posts/{}\".format(i)\n resp = await session.get(host, headers=headers)\n await resp.text()\n\n\nDocumentation\n-------------\nhttp://aiozipkin.readthedocs.io/\n\n\nInstallation\n------------\nInstallation process is simple, just::\n\n $ pip install aiozipkin\n\n\nSupport of other collectors\n===========================\n**aiozipkin** can work with any other zipkin_ compatible service, currently we\ntested it with jaeger_ and stackdriver_.\n\n\nJaeger support\n--------------\njaeger_ supports zipkin_ span format as result it is possible to use *aiozipkin*\nwith jaeger_ server. You just need to specify *jaeger* server address and it\nshould work out of the box. Not need to run local zipkin server.\nFor more informations see tests and jaeger_ documentation.\n\n.. image:: https://raw.githubusercontent.com/aio-libs/aiozipkin/master/docs/jaeger.png\n :alt: jaeger ui animation\n\n\nStackdriver support\n-------------------\nGoogle stackdriver_ supports zipkin_ span format as result it is possible to\nuse *aiozipkin* with this google_ service. In order to make this work you\nneed to setup zipkin service locally, that will send trace to the cloud. See\ngoogle_ cloud documentation how to setup make zipkin collector:\n\n.. image:: https://raw.githubusercontent.com/aio-libs/aiozipkin/master/docs/stackdriver.png\n :alt: jaeger ui animation\n\n\nRequirements\n------------\n\n* Python_ 3.6+\n* aiohttp_\n\n\n.. _PEP492: https://www.python.org/dev/peps/pep-0492/\n.. _Python: https://www.python.org\n.. _aiohttp: https://github.com/KeepSafe/aiohttp\n.. _asyncio: http://docs.python.org/3.5/library/asyncio.html\n.. _uvloop: https://github.com/MagicStack/uvloop\n.. _zipkin: http://zipkin.io\n.. _jaeger: http://jaeger.readthedocs.io/en/latest/\n.. _stackdriver: https://cloud.google.com/stackdriver/\n.. _google: https://cloud.google.com/trace/docs/zipkin\n\nCHANGES\n=======\n\n..\n You should *NOT* be adding new change log entries to this file, this\n file is managed by towncrier. You *may* edit previous change logs to\n fix problems like typo corrections or such.\n To add a new change log entry, please see\n https://pip.pypa.io/en/latest/development/#adding-a-news-entry\n we named the news folder \"changes\".\n\n WARNING: Don't drop the next directive!\n\n.. towncrier release notes start\n\n1.1.1 (2021-10-23)\n==================\n\nBugfixes\n--------\n\n- Fix unhandled AssertionError in aiohttp integration when unknown resource requested by the user.\n `#400 <https://github.com/aio-libs/aiozipkin/issues/400>`_\n- Fix ``NoneType`` error when using ``SystemRoute``.\n `#410 <https://github.com/aio-libs/aiozipkin/issues/410>`_\n\n----\n\n\n1.1.0 (2021-05-17)\n==================\n\nBugfixes\n--------\n\n- Expect trace request context to be of SimpleNamespace type.\n `#385 <https://github.com/aio-libs/aiozipkin/issues/385>`_\n\n\n----\n\n\n1.0.0 (2020-11-06)\n==================\n\nBugfixes\n--------\n\n- Support Python 3.8 and Python 3.9\n `#259 <https://github.com/aio-libs/aiozipkin/issues/259>`_\n\n\n----\n\n\n0.7.1 (2020-09-20)\n==================\n\nBugfixes\n--------\n\n- Fix `Manifest.in` file; add `CHANGES.rst` to the Source Tarball.\n\n\n0.7.0 (2020-07-17)\n==================\n\nFeatures\n--------\n\n- Add support of AWS X-Ray trace id format.\n `#273 <https://github.com/aio-libs/aiozipkin/issues/273>`_\n\n\n----\n\n\n0.6.0 (2019-10-12)\n------------------\n* Add context var support for python3.7 aiohttp instrumentation #187\n* Single header tracing support #189\n* Add retries and batches to transport (thanks @konstantin-stepanov)\n* Drop python3.5 support #238\n* Use new typing syntax in codebase #237\n\n\n0.5.0 (2018-12-25)\n------------------\n* More strict typing configuration is used #147\n* Fixed bunch of typos in code and docs #151 #153 (thanks @deejay1)\n* Added interface for Transport #155 (thanks @deejay1)\n* Added create_custom helper for easer tracer configuration #160 (thanks @deejay1)\n* Added interface for Sampler #160 (thanks @deejay1)\n* Added py.typed marker\n\n\n0.4.0 (2018-07-11)\n------------------\n* Add more coverage with typing #147\n* Breaking change: typo send_inteval => send_interval #144 (thanks @gugu)\n* Breaking change: do not append api/v2/spans to the zipkin dress #150\n\n\n0.3.0 (2018-06-13)\n------------------\n* Add support http.route tag for aiohttp #138\n* Make zipkin address builder more permissive #141 (thanks @dsantosfff)\n\n\n0.2.0 (2018-03-03)\n------------------\n* Breaking change: az.create is coroutine now #114\n* Added context manger for tracer object #114\n* Added more mypy types #117\n\n\n0.1.1 (2018-01-26)\n------------------\n* Added new_child helper method #83\n\n\n0.1.0 (2018-01-21)\n------------------\nAfter few months of work and beta releases here are basic features:\n\n* Initial release.\n* Implemented zipkin v2 protocol with HTTP transport\n* Added jaeger support\n* Added stackdriver support\n* Added aiohttp server support\n* Added aiohttp 3.0.0 client tracing support\n* Added examples and demos\n\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "Distributed tracing instrumentation for asyncio application with zipkin",
"version": "1.1.1",
"project_urls": {
"Download": "https://pypi.python.org/pypi/aiozipkin",
"Homepage": "https://github.com/aio-libs/aiozipkin"
},
"split_keywords": [
"zipkin",
"distributed-tracing",
"tracing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e63dffb37f488cfb630f52483c2ed65a922e34b5c333ff2390a0218fb51fa3bc",
"md5": "745d56c5f5aa7a019fd5256bfd978719",
"sha256": "6f891d35dfe2e517d4ca7155701a38766c56cdb19459e6c637b78ba2efb7fbc7"
},
"downloads": -1,
"filename": "aiozipkin-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "745d56c5f5aa7a019fd5256bfd978719",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 23617,
"upload_time": "2021-10-23T11:16:23",
"upload_time_iso_8601": "2021-10-23T11:16:23.737616Z",
"url": "https://files.pythonhosted.org/packages/e6/3d/ffb37f488cfb630f52483c2ed65a922e34b5c333ff2390a0218fb51fa3bc/aiozipkin-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2fe26a60a7c9e91c968eac5dacab2948ed931a676880a6878695ff281c72b8f",
"md5": "0fea8a200ab2a94fe9a2340a8cbf8512",
"sha256": "9b82619d9ef309e72627a81ab3fda0c9b83e530844cf59f2e9a011e9a2a1293f"
},
"downloads": -1,
"filename": "aiozipkin-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "0fea8a200ab2a94fe9a2340a8cbf8512",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 24144,
"upload_time": "2021-10-23T11:16:24",
"upload_time_iso_8601": "2021-10-23T11:16:24.659231Z",
"url": "https://files.pythonhosted.org/packages/f2/fe/26a60a7c9e91c968eac5dacab2948ed931a676880a6878695ff281c72b8f/aiozipkin-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-10-23 11:16:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aio-libs",
"github_project": "aiozipkin",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "aiozipkin"
}
JSON
