Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better documentation - generate readthedocs compatible docs #127

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Better documentation - generate readthedocs compatible docs #127

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
Changelog
=========

0.18.1 (2019-02-22)
-------------------
- Fix ThreadLocalStack() bug introduced in 0.18.0
Expand Down
8 changes: 7 additions & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,21 @@ install:
install-hooks:
tox -e pre-commit -- install -f --install-hooks

test:
test: install-hooks
tox

.PHONY: tests
tests: test

.PHONY: docs
docs:
tox -e docs

clean:
@rm -rf .tox build dist *.egg-info
find . -name '*.pyc' -delete
find . -name '__pycache__' -delete
@rm -rf docs/build

update-protobuf:
$(MAKE) -C py_zipkin/encoding/protobuf update-protobuf
248 changes: 25 additions & 223 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,251 +1,53 @@
[![Build Status](https://travis-ci.org/Yelp/py_zipkin.svg?branch=master)](https://travis-ci.org/Yelp/py_zipkin)
[![Coverage Status](https://img.shields.io/coveralls/Yelp/py_zipkin.svg)](https://coveralls.io/r/Yelp/py_zipkin)
[![Docs Status](https://readthedocs.org/projects/py-zipkin/badge/?version=latest)](https://py_zipkin.readthedocs.io)
[![PyPi version](https://img.shields.io/pypi/v/py_zipkin.svg)](https://pypi.python.org/pypi/py_zipkin/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/py_zipkin.svg)](https://pypi.python.org/pypi/py_zipkin/)

py_zipkin
---------
# py_zipkin

py_zipkin provides a context manager/decorator along with some utilities to
facilitate the usage of Zipkin in Python applications.

Install
-------

```
pip install py_zipkin
```

Usage
-----

py_zipkin requires a `transport_handler` object that handles logging zipkin
messages to a central logging service such as kafka or scribe.

`py_zipkin.zipkin.zipkin_span` is the main tool for starting zipkin traces or
logging spans inside an ongoing trace. zipkin_span can be used as a context
manager or a decorator.

#### Usage #1: Start a trace with a given sampling rate

```python
from py_zipkin.zipkin import zipkin_span

def some_function(a, b):
with zipkin_span(
service_name='my_service',
span_name='my_span_name',
transport_handler=some_handler,
port=42,
sample_rate=0.05, # Value between 0.0 and 100.0
):
do_stuff(a, b)
```

#### Usage #2: Trace a service call

The difference between this and Usage #1 is that the zipkin_attrs are calculated
separately and passed in, thus negating the need of the sample_rate param.

```python
# Define a pyramid tween
def tween(request):
zipkin_attrs = some_zipkin_attr_creator(request)
with zipkin_span(
service_name='my_service',
span_name='my_span_name',
zipkin_attrs=zipkin_attrs,
transport_handler=some_handler,
port=22,
) as zipkin_context:
response = handler(request)
zipkin_context.update_binary_annotations(
some_binary_annotations)
return response
```

#### Usage #3: Log a span inside an ongoing trace

This can be also be used inside itself to produce continuously nested spans.

```python
@zipkin_span(service_name='my_service', span_name='some_function')
def some_function(a, b):
return do_stuff(a, b)
```

#### Other utilities

`zipkin_span.update_binary_annotations()` can be used inside a zipkin trace
to add to the existing set of binary annotations.

```python
def some_function(a, b):
with zipkin_span(
service_name='my_service',
span_name='some_function',
transport_handler=some_handler,
port=42,
sample_rate=0.05,
) as zipkin_context:
result = do_stuff(a, b)
zipkin_context.update_binary_annotations({'result': result})
```
## Install

`zipkin_span.add_sa_binary_annotation()` can be used to add a binary annotation
to the current span with the key 'sa'. This function allows the user to specify the
destination address of the service being called (useful if the destination doesn't
support zipkin). See http://zipkin.io/pages/data_model.html for more information on the
'sa' binary annotation.

> NOTE: the V2 span format only support 1 "sa" endpoint (represented by remoteEndpoint)
> so `add_sa_binary_annotation` now raises `ValueError` if you try to set multiple "sa"
> annotations for the same span.

```python
def some_function():
with zipkin_span(
service_name='my_service',
span_name='some_function',
transport_handler=some_handler,
port=42,
sample_rate=0.05,
) as zipkin_context:
make_call_to_non_instrumented_service()
zipkin_context.add_sa_binary_annotation(
port=123,
service_name='non_instrumented_service',
host='12.34.56.78',
)
```

`create_http_headers_for_new_span()` creates a set of HTTP headers that can be forwarded
in a request to another service.

```python
headers = {}
headers.update(create_http_headers_for_new_span())
http_client.get(
path='some_url',
headers=headers,
)
pip install py-zipkin
```

Transport
---------

py_zipkin (for the moment) thrift-encodes spans. The actual transport layer is
pluggable, though.

The recommended way to implement a new transport handler is to subclass
`py_zipkin.transport.BaseTransportHandler` and implement the `send` and
`get_max_payload_bytes` methods.

`send` receives an already encoded thrift list as argument.
`get_max_payload_bytes` should return the maximum payload size supported by your
transport, or `None` if you can send arbitrarily big messages.

The simplest way to get spans to the collector is via HTTP POST. Here's an
example of a simple HTTP transport using the `requests` library. This assumes
your Zipkin collector is running at localhost:9411.

> NOTE: older versions of py_zipkin suggested implementing the transport handler
> as a function with a single argument. That's still supported and should work
> with the current py_zipkin version, but it's deprecated.

```python
import requests
## Documentation

from py_zipkin.transport import BaseTransportHandler
Full documentation is available at https://py_zipkin.readthedocs.io.

## Developing

class HttpTransport(BaseTransportHandler):
To run the tests after making changes run: `make test`.

def get_max_payload_bytes(self):
return None
To run the tests only against one python version use: `tox -e py37`.

def send(self, encoded_span):
# The collector expects a thrift-encoded list of spans.
requests.post(
'http://localhost:9411/api/v1/spans',
data=encoded_span,
headers={'Content-Type': 'application/x-thrift'},
)
```

If you have the ability to send spans over Kafka (more like what you might do
in production), you'd do something like the following, using the
[kafka-python](https://pypi.python.org/pypi/kafka-python) package:

```python
from kafka import SimpleProducer, KafkaClient
### Docs

from py_zipkin.transport import BaseTransportHandler
Docs are generated using [sphinx](https://www.sphinx-doc.org/en/master/index.html).
To regenerate them run: `make docs`. They’ll be automatically uploaded to
[readthedocs.io](https://py_zipkin.readthedocs.io) by travis once you release a new
version.

### Releasing a new version

class KafkaTransport(BaseTransportHandler):
First of all, bump the version in setup.py and update the CHANGELOG. We follow
[semver](https://semver.org/) versioning, so follow those rules in deciding the next
version.

def get_max_payload_bytes(self):
# By default Kafka rejects messages bigger than 1000012 bytes.
return 1000012

def send(self, message):
kafka_client = KafkaClient('{}:{}'.format('localhost', 9092))
producer = SimpleProducer(kafka_client)
producer.send_messages('kafka_topic_name', message)
```
Commit the changes and tag the commit as `vX.Y.Z`. Example:

Using in multithreading evironments
-----------------------------------

If you want to use py_zipkin in a cooperative multithreading environment,
e.g. asyncio, you need to explicitly pass an instance of `py_zipkin.storage.Stack`
as parameter `context_stack` for `zipkin_span` and `create_http_headers_for_new_span`.
By default, py_zipkin uses a thread local storage for the attributes, which is
defined in `py_zipkin.storage.ThreadLocalStack`.

Additionally, you'll also need to explicitly pass an instance of
`py_zipkin.storage.SpanStorage` as parameter `span_storage` to `zipkin_span`.

```python
from py_zipkin.zipkin import zipkin_span
from py_zipkin.storage import Stack
from py_zipkin.storage import SpanStorage


def my_function():
context_stack = Stack()
span_storage = SpanStorage()
await my_function(context_stack, span_storage)

async def my_function(context_stack, span_storage):
with zipkin_span(
service_name='my_service',
span_name='some_function',
transport_handler=some_handler,
port=42,
sample_rate=0.05,
context_stack=context_stack,
span_storage=span_storage,
):
result = do_stuff(a, b)
```bash
git commit -m 'release version 1.0.0'
git tag v1.0.0
git push origin master --tags
```


Firehose mode [EXPERIMENTAL]
----------------------------

"Firehose mode" records 100% of the spans, regardless of
sampling rate. This is useful if you want to treat these spans
differently, e.g. send them to a different backend that has limited
retention. It works in tandem with normal operation, however there may
be additional overhead. In order to use this, you add a
`firehose_handler` just like you add a `transport_handler`.

This feature should be considered experimental and may be removed at
any time without warning. If you do use this, be sure to send
asynchronously to avoid excess overhead for every request.

Travis will automatically detect tagged commits, build the wheel and upload it to
[pypi](https://pypi.org/project/py-zipkin/).

License
-------
Expand Down
1 change: 1 addition & 0 deletions docs/source/CHANGELOG.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../../CHANGELOG.rst
1 change: 1 addition & 0 deletions docs/source/DEPRECATIONS.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../../DEPRECATIONS.rst
Loading