Release updates (#4)

* add tracer init to readme

* added build and release features

* fix makefile typo

* can enable shared spans if desired

Author: rhilfers

.travis.yml

@@ -1,11 +1,25 @@
 sudo: required
 
 dist: trusty
-
 language: python
+python: 3.6
 
 services:
   - docker
-  
-install:
-  - make bootstrap
+
+install: make bootstrap
+
+script: make lint test integration_tests
+
+before_deploy:
+  - git stash --all
+  - make set_version
+deploy:
+  provider: pypi
+  user: $PYPI_USERNAME
+  password: $PYPI_PASSWORD
+  distributions: "sdist bdist_wheel"
+  skip_cleanup: true
+  on:
+    branch: master
+    tags: true

Makefile

@@ -17,31 +17,27 @@ example: bootstrap
 .PHONY: lint
 lint:
 	pip install flake8
-	python -m flake8 ./haystack --exclude *_pb2*
+	python -m flake8 ./haystack --exclude *_pb2* && echo "Flake8 passed without any issues!"
 
 .PHONY: integration_tests
 integration_tests:
 	docker-compose -f tests/integration/docker-compose.yml -p sandbox up -d
+	echo "sleeping for 15s while kafka/zookeeper initialize"
 	sleep 15
-	docker run -it
+	docker run -it \
 	    --rm \
 		--network=sandbox_default \
-		-v $(pwd):/ws \
+		-v $(PWD):/ws \
 		-w /ws \
 		python:3.6 \
 		/bin/sh -c 'python setup.py install && pip install kafka-python && python tests/integration/integration.py'
 	docker-compose -f tests/integration/docker-compose.yml -p sandbox stop
 
-.PHONY: dist
-dist: bootstrap lint test integration_tests
-	pip install wheel
-	python setup.py sdist
-	python setup.py bdist_wheel
-	
-.PHONY: publish
-publish:
-	pip install twine
-	python -m twine upload dist/*
+.PHONY: set_version
+set_version:
+	pip install semver
+	pip install requests
+	python ./scripts/version.py
 
 .PHONY: proto_compile
 proto_compile:

README.md

@@ -1,3 +1,6 @@
+[![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/)
 
@@ -6,11 +9,20 @@ Further information can be found on [opentracing.io](https://opentracing.io/)
 ## Using this library
 See examples in /examples directory. 
 
+First initialize the tracer at the application level by supplying a service name and recorder
+```python
+import opentracing
+from haystack import HaystackAgentRecorder
+from haystack import HaystackTracer
+
+opentracing.tracer = HaystackTracer("a_service", HaystackAgentRecorder())
+```
+
 **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`
 
-As demonstrated in the examples, starting a span can be done as a managed resource using `start_active_span()`
+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()
@@ -38,4 +50,4 @@ Create a python3 virtual environment, activate it and then `make bootstrap`
 `make example`
 
 ## How to Release this library
-TBD
+Create a new release in github specifying a semver compliant tag greater than the current release version.

haystack/constants.py

@@ -1,14 +1,13 @@
 # Name of the HTTP header or Key used to encode Trace ID
 TRACE_ID_HEADER = "Trace-ID"
 
-# Name of the HTTP header or Key used to encode Span ID
-SPAN_ID_HEADER = "Span-ID"
+# Name of the HTTP header or Key used to encode Span ID followed by any
+# alternate header names to extract as Span ID
+SPAN_ID_HEADERS = ("Span-ID", "Message-ID",)
 
-# Any additional header names to decode Span ID
-ALTERNATE_SPAN_ID_HEADERS = ["Message-ID", ]
-
-# Name of the HTTP header or Key used to encode Parent Span ID
-PARENT_SPAN_ID_HEADER = "Parent-ID"
+# Name of the HTTP header or Key used to encode Parent Span ID followed by any
+# alternate header names to extract as Parent Span ID
+PARENT_SPAN_ID_HEADERS = ("Parent-ID", "Parent-Message-ID",)
 
 # Prefix of the HTTP header or Key used to encode Baggage items
 BAGGAGE_HEADER_PREFIX = "Baggage-"

haystack/text_propagator.py

@@ -2,11 +2,10 @@
 from .span import SpanContext
 from opentracing import SpanContextCorruptedException
 from .constants import (
-    SPAN_ID_HEADER,
+    SPAN_ID_HEADERS,
     TRACE_ID_HEADER,
-    PARENT_SPAN_ID_HEADER,
+    PARENT_SPAN_ID_HEADERS,
     BAGGAGE_HEADER_PREFIX,
-    ALTERNATE_SPAN_ID_HEADERS,
 )
 
 
@@ -15,8 +14,8 @@ class TextPropagator(Propagator):
 
     def inject(self, span_context, carrier):
         carrier[TRACE_ID_HEADER] = span_context.trace_id
-        carrier[SPAN_ID_HEADER] = span_context.span_id
-        carrier[PARENT_SPAN_ID_HEADER] = span_context.parent_id
+        carrier[SPAN_ID_HEADERS[0]] = span_context.span_id
+        carrier[PARENT_SPAN_ID_HEADERS[0]] = span_context.parent_id
         if span_context.baggage is not None:
             for item in span_context.baggage:
                 carrier[BAGGAGE_HEADER_PREFIX + item] = \
@@ -25,24 +24,28 @@ def inject(self, span_context, carrier):
     def extract(self, carrier):
         count = 0
         baggage = {}
+        parent_id = None
 
         for key in carrier:
             value = carrier[key]
-            if key == SPAN_ID_HEADER:
+            if key in SPAN_ID_HEADERS:
                 span_id = value
                 count += 1
             elif key == TRACE_ID_HEADER:
                 trace_id = value
                 count += 1
             elif key.startswith(BAGGAGE_HEADER_PREFIX):
                 baggage[key[len(BAGGAGE_HEADER_PREFIX):]] = value
-            elif key in ALTERNATE_SPAN_ID_HEADERS:
-                span_id = value
-                count += 1
+            elif key in PARENT_SPAN_ID_HEADERS:
+                parent_id = value
 
         if count == 0:
             return None
         elif count != 2:
-            raise SpanContextCorruptedException()
+            raise SpanContextCorruptedException(
+                "Both SpanID and TraceID are required")
 
-        return SpanContext(span_id=span_id, trace_id=trace_id, baggage=baggage)
+        return SpanContext(span_id=span_id,
+                           trace_id=trace_id,
+                           parent_id=parent_id,
+                           baggage=baggage)

haystack/tracer.py

@@ -12,7 +12,8 @@ def __init__(self,
                  service_name,
                  recorder,
                  scope_manager=None,
-                 common_tags=None):
+                 common_tags=None,
+                 use_shared_spans=False):
         """
         Initialize a Haystack Tracer instance.
         :param service_name: The service name to which all spans will belong.
@@ -22,6 +23,9 @@ def __init__(self,
         ThreadLocal scope manager.
         :param common_tags: An optional dictionary of tags which should be
         applied to all created spans for this service
+        :param use_shared_spans: A boolean indicating whether or not to use
+        shared spans. This is when client/server spans share the same span id.
+        Default is to use unique span ids.
         """
 
         scope_manager = ThreadLocalScopeManager() if scope_manager is None \
@@ -31,6 +35,7 @@ def __init__(self,
         self._common_tags = {} if common_tags is None else common_tags
         self.service_name = service_name
         self.recorder = recorder
+        self.use_shared_spans = use_shared_spans
         self.register_propagator(Format.TEXT_MAP, TextPropagator())
         self.register_propagator(Format.HTTP_HEADERS, TextPropagator())
 
@@ -87,10 +92,14 @@ def start_span(self,
 
         new_ctx = SpanContext(span_id=format(uuid.uuid4()))
         if parent_ctx is not None:
+            new_ctx.trace_id = parent_ctx.trace_id
             if parent_ctx.baggage is not None:
                 new_ctx._baggage = parent_ctx.baggage.copy()
-            new_ctx.trace_id = parent_ctx.trace_id
-            new_ctx.parent_id = parent_ctx.span_id
+            if self.use_shared_spans:
+                new_ctx.span_id = parent_ctx.span_id
+                new_ctx.parent_id = parent_ctx.parent_id
+            else:
+                new_ctx.parent_id = parent_ctx.span_id
         else:
             new_ctx.trace_id = format(uuid.uuid4())
 

scripts/version.py

@@ -0,0 +1,57 @@
+import requests
+import json
+import semver
+import os
+
+
+VERSION_PLACEHOLDER = "X.X.X"
+
+
+def update_setup(new_version):
+    with open("setup.py") as f:
+        content = f.read()
+        if VERSION_PLACEHOLDER not in content:
+            raise Exception("setup.py version parameter has been modified")
+
+    with open("setup.py", "w") as f:
+        print("changing setup.py version parameter")
+        content = content.replace(VERSION_PLACEHOLDER, new_version)
+        f.write(content)
+
+
+def pypi_version(response):
+    data = json.loads(response.text)
+    if "info" in data:
+        return data["info"]["version"]
+    else:
+        raise Exception(f"Invalid response {data} from pypi. "
+                        f"info tag missing")
+
+
+if __name__ == "__main__":
+    tag_ver = os.getenv("TRAVIS_TAG")
+
+    if tag_ver is None:
+        raise TypeError("Expected TRAVIS_TAG environment variable to be set")
+
+    # verify tag is valid semver
+    semver.parse(tag_ver)
+
+    response = requests.get("https://pypi.org/pypi/haystack-client/json")
+
+    if response.ok:
+        old_ver = pypi_version(response)
+    elif response.status_code == 404:
+        print("must be a new repo")
+        old_ver = "0.0.0"
+    else:
+        raise Exception(f"Failed to get existing version information from pypi."
+                        f" Response was {response}")
+
+    if semver.compare(tag_ver, old_ver) > 0:
+        print(f"Previouis PyPI version is {old_ver}, updating setup.py with new"
+              f" version {tag_ver}")
+        update_setup(tag_ver)
+    else:
+        raise Exception(f"pypi version {old_ver} is newer than tagged version"
+                        f" {tag_ver}")

setup.py

@@ -1,11 +1,17 @@
 from setuptools import setup, find_packages
 
+with open("README.md") as file:
+    long_description = file.read()
+
 setup(
     name="haystack-client",
-    version="1.0.0",
+    version="X.X.X",  # do not change, makefile updates this prior to a release
+    url="https://github.com/ExpediaDotCom/haystack-client-python",
     description="Haystack Python OpenTracing Implementation",
     author="Ryan Hilfers, Haystack",
     author_email="[email protected]",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
     install_requires=["opentracing==2.0.0",
                       "requests>=2.19,<3.0",
                       "requests-futures==0.9.9,<1.0",
@@ -24,6 +30,6 @@
         "License :: OSI Approved :: Apache Software License",
     ],
     python_requires=">=3.5",
-    keywords=['opentracing', 'haystack', 'tracing', 'microservices', 'distributed'],
+    keywords=["opentracing", "haystack", "tracing", "microservices", "distributed"],
     packages=find_packages()
 )

tests/unit/test_text_propagator.py

@@ -10,15 +10,21 @@ def setUp(self):
 
     def test_message_id_in_carrier_should_be_extracted_as_span_id(self):
         span_id = "1234"
-        carrier = {"Message-ID": span_id, "Trace-ID": "123456"}
+        parent_id = "4321"
+        trace_id = "1212"
+        carrier = {"Message-ID": span_id, "Parent-Message-ID": parent_id,
+                   "Trace-ID": trace_id}
 
         ctx = self.propagator.extract(carrier)
 
         self.assertEqual(ctx.span_id, span_id)
+        self.assertEqual(ctx.parent_id, parent_id)
+        self.assertEqual(ctx.trace_id, trace_id)
 
     def test_corrupted_context_throws_exception(self):
         span_id = "1234"
-        carrier = {"Message-ID": span_id, "Span-ID": "123456", "Trace-ID": "1234567"}  # two span id's are invalid
+        carrier = {"Message-ID": span_id, "Span-ID": "123456",
+                   "Trace-ID": "1234567"}  # two span id's are invalid
 
         self.assertRaises(SpanContextCorruptedException, self.propagator.extract, carrier)