Metadata-Version: 2.1
Name: haystack-client
Version: 0.2.4
Summary: Haystack Python OpenTracing Implementation
Home-page: https://github.com/ExpediaDotCom/haystack-client-python
Author: Ryan Hilfers, Haystack
Author-email: haystack@expediagroup.com
License: UNKNOWN
Keywords: opentracing,haystack,tracing,microservices,distributed
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.5
Description-Content-Type: text/markdown
Requires-Dist: opentracing (<3.0,>=2.3.0)
Requires-Dist: requests (<3.0,>=2.19)
Requires-Dist: requests-futures (<1.0,>=0.9.9)
Requires-Dist: protobuf (<4.0,>=3.11.2)
Requires-Dist: grpcio (<2.0,>=1.26.0)

[![Build Status](https://travis-ci.org/ExpediaDotCom/haystack-client-python.svg?branch=master)](https://travis-ci.org/ExpediaDotCom/haystack-client-python)
[![License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg)](https://github.com/ExpediaDotCom/haystack/blob/master/LICENSE)

# Haystack bindings for Python OpenTracing API
This is Haystack's client library for Python that implements [OpenTracing](https://github.com/opentracing/opentracing-python/)

Further information can be found on [opentracing.io](https://opentracing.io/) 

## Using this library
See examples in /examples directory. See opentracing [usage](https://github.com/opentracing/opentracing-python/#usage) for additional information.

It is important to consider the architecture of the application. In order for the tracer to manage spans properly, an appropriate `ScopeManager` implementation must be chosen.  In most environments, the default `ThreadLocalScopeManager` will work just fine. In asynchronous frameworks, the `ContextVarsScopeManager` is a better choice.  

First initialize the tracer at the application level by supplying a service name and span recorder
```python
import opentracing
from haystack import HaystackAgentRecorder
from haystack import HaystackTracer

tracer = HaystackTracer("a_service", HaystackAgentRecorder())
opentracing.set_global_tracer(tracer)
```

Starting a span can be done as a managed resource using `start_active_span()`
```python
with opentracing.tracer.start_active_span("span-name") as scope:
    do_stuff()
```

or finish the span on your own terms with
```python
span = opentracing.tracer.start_span("span-name")
do_stuff()
span.finish()
```

Note: **If there is a Scope, it will act as the parent to any newly started Span** unless the programmer passes 
`ignore_active_span=True` at `start_span()/start_active_span()` time or specified parent context explicitly using 
`childOf=parent_context`

#### Custom propagation headers
If necessary, default propagation headers can be replaced with custom ones by specifying custom propagator options. Register the new propagator with the tracer once configured. 
```python
prop_opts = PropagatorOpts("X-Trace-ID", "X-Span-ID", "X-Parent-Span", "X-baggage-")
opentracing.tracer.register_propagator(opentracing.Format.HTTP_HEADERS, TextPropagator(prop_opts))
```

#### Logging
All modules define their logger via `logging.getLogger(__name__)`

So in order to define specific logging format or level for this library use `getLogger('haystack')` or configure the
root logger.

## How to configure build environment
Create a python3 virtual environment, activate it and then `make bootstrap`

## Running the example code
`make example`

## How to Release this library
Create a new release in github specifying a semver compliant tag greater than the current release version.

