aiozipkin 1.1.1

zipkin vocabulary

Before code lets learn important zipkin vocabulary, for more detailed information please visit https://zipkin.io/pages/instrumenting

• 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

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:

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.

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

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.

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:

Requirements

• Python 3.6+

• aiohttp

Features

• Add support of AWS X-Ray trace id format. #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