added README

Author: ror6ax

example/README.md

@@ -1,74 +1,81 @@
 ## Example
 
-This example has a flask client and server and shows they can trace requests
-both within and between the two sites using the flask_opentracing extension and
+This example has a flask client and server and shows how to trace the requests
+to a webserver from a client using the flask_opentracing extension and
 a concrete variant of an OpenTracing tracer. To run, make sure that you run pip
-install for flask, opentracing, and lightstep (although you will not be able to
-view the lightstep traces unless you have an access token).
+install for flask, opentracing, jaeger_client.
 
-Open two terminals and navigate to this directory. Run the following commands in
-each terminal:
+### Set up Jaeger:
 
-First window:
+First, we'll have to download and run our Jaeger instance. It collects and displays
+traces in neat graphical format.
 
-``` 
-> export FLASK_APP=server.py   
-> flask run 
+If you already have Docker installed, run this:
+
+```
+docker run -d -e \
+  COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
+  -p 5775:5775/udp \
+  -p 6831:6831/udp \
+  -p 6832:6832/udp \
+  -p 5778:5778 \
+  -p 16686:16686 \
+  -p 14268:14268 \
+  -p 9411:9411 \
+  jaegertracing/all-in-one:latest
 ```
 
-Second window:
+You should be able to see a web interface by browsing to http://localhost:16686/search
 
-``` 
-> export FLASK_APP=client.py   
-> flask run --port=0 
+![traced request](https://raw.githubusercontent.com/opentracing-contrib/python-flask/example/example/img/jaeger_0.png)
+
+Now, open two terminals and navigate to this directory. Run the following commands in
+each terminal:
+
+First window:
+
+```
+> python3 server.py   
 ```
 
-To test the traces, check what port the client is running on and load
-localhost:port. If you have a lightstep tracer token, you
-should be able to view the trace data on the lightstep interface. 
-(NOTE: if you wish to use a different OpenTracing tracer, simply replace
-`ls_tracer` with the OpenTracing tracer instance of your choice.)
+Give it few seconds to start and run this in second window:
 
-### Trace a request:
+```
+> python3 client.py   
+```
 
-Navigate to `/request/simple/<int:numrequests>` where numrequests is the number
-of requests you want to send to the page. This will send a request to the server
-app, and the trace will include a span on both the client and server sides. This
-occurs automatically since both the client and server functions are decorated
-with @tracer.trace().
+To see the traced requests, go to Jaeger web interface.
+Select your service name from dropdown on the left (it's
+"jaeger_opentracing_example" in our case) and press Find traces button at the bottom of the page.
 
-Result for `/request/simple/1`:
 
-![request and response spans](https://raw.githubusercontent.com/kcamenzind/flask_opentracing/master/example/img/simple.png)
+![traced request](https://raw.githubusercontent.com/opentracing-contrib/python-flask/example/example/img/jaeger.png)
 
-### Log something to a request:
 
-Navigate to `/log`. This will log a message to the server-side span. The client
-span is created automatically through the @tracer.trace() decorator, while the
-logging occurs within the function by accessing the current span as follows:
+(NOTE: if you wish to use a different OpenTracing tracer instead of Jaeger, simply replace
+`jaeger_tracer` with the OpenTracing tracer instance of your choice.)
 
-```python
-span = tracer.get_span()
-span.log_event("hello world")
-```
-Result for `/log`:
+### Trace a request from browser:
 
-![span with log](https://raw.githubusercontent.com/kcamenzind/flask_opentracing/master/example/img/log.png)
+Browse to http://localhost:5000/log and compare the trace in Jaeger.
+The last one has 2 spans instead of 3. The span of webserver's GET method is missing.
+That is because in client.py we pass already existing span over the wire, whereas the request from your browser has to tracing data in it.
 
 ### Add spans to the trace manually:
 
-Navigate to `/request/childspan/<int:numrequests>`. This will send a request to
-the server app, and the trace will include a span on both the client and server
-sides. The server app will additionally create a child span for the server-side
-span. This example demonstrates how you can trace non-RPC function calls in your
-app, through accessing the current span as follows:
+In log function of the server app, we are creating current_span. This is done to
+trace the work that is being done to render the response to /log. Suppose there's
+a database connection happening. By creating a separate span for it, you'll be able
+to trace the DB request separately from rendering or the response. This gives a
+lot of flexibility to the user.
+
+Following code shows how to create a span based on already existing one.
 
 ```python
 parent_span = tracer.get_span()
-child_span = ls_tracer.start_span("inside create_child_span", parent_span)
+child_span = jaeger_tracer.start_span("inside create_child_span", parent_span)
 ... do some stuff
-child_span.finish()	
+child_span.finish()
 ```
-Result for `/request/childspan/2`:
 
-![two child spans](https://raw.githubusercontent.com/kcamenzind/flask_opentracing/master/example/img/childspan.png)
+![traced request](https://raw.githubusercontent.com/opentracing-contrib/python-flask/example/example/img/jaeger_1.png)

example/client.py

@@ -1,35 +1,27 @@
 import requests
 import time
 from opentracing_instrumentation.client_hooks import install_all_patches
-from opentracing_instrumentation.request_context import get_current_span, span_in_context
 from jaeger_client import Config
-from opentracing.ext import tags
-from opentracing.propagation import Format
 
-from os import environ
+from os import getenv
 
-JAEGER_HOST = environ.get('JAEGER_HOST')
-
-WEBSERVER_HOST = environ.get('WEBSERVER_HOST')
+JAEGER_HOST = getenv('JAEGER_HOST', 'localhost')
+WEBSERVER_HOST = getenv('WEBSERVER_HOST', 'localhost')
 
+# Create configuration object with enabled logging and sampling of all requests.
 config = Config(config={'sampler': {'type': 'const', 'param': 1},
                         'logging': True,
                         'local_agent': {'reporting_host': JAEGER_HOST}},
                 service_name="jaeger_opentracing_example")
 tracer = config.initialize_tracer()
 
+# Automatically trace all requests made with 'requests' library.
 install_all_patches()
 
 url = "http://{}:5000/log".format(WEBSERVER_HOST)
-with tracer.start_span('say-hello') as span:
-    span.set_tag(tags.HTTP_METHOD, 'GET')
-    span.set_tag(tags.HTTP_URL, url)
-    span.set_tag(tags.SPAN_KIND, tags.SPAN_KIND_RPC_CLIENT)
-    headers = {}
-    tracer.inject(span, Format.HTTP_HEADERS, headers)
-
-    r = requests.get(url, headers=headers)
-    print(r.text)
+# Make the actual request to webserver.
+requests.get(url)
 
-    time.sleep(2)
-    tracer.close()
+# allow tracer to flush the spans - https://github.com/jaegertracing/jaeger-client-python/issues/50
+time.sleep(2)
+tracer.close()

example/img/childspan.png

@@ -1,40 +1,43 @@
-import opentracing
 import logging
 from jaeger_client import Config
 from flask_opentracing import FlaskTracer
-from opentracing.propagation import Format
 from flask import Flask, request
-from opentracing.ext import tags
-from os import environ
-
-JAEGER_HOST = environ.get('JAEGER_HOST')
+from os import getenv
+JAEGER_HOST = getenv('JAEGER_HOST', 'localhost')
 
 if __name__ == '__main__':
         app = Flask(__name__)
         log_level = logging.DEBUG
         logging.getLogger('').handlers = []
         logging.basicConfig(format='%(asctime)s %(message)s', level=log_level)
+        # Create configuration object with enabled logging and sampling of all requests.
         config = Config(config={'sampler': {'type': 'const', 'param': 1},
                                 'logging': True,
                                 'local_agent':
+                                # Also, provide a hostname of Jaeger instance to send traces to.
                                 {'reporting_host': JAEGER_HOST}},
+                        # Service name can be arbitrary string describing this particular web service.
                         service_name="jaeger_opentracing_example")
-        ls_tracer = config.initialize_tracer()
-        tracer = FlaskTracer(ls_tracer)
+        jaeger_tracer = config.initialize_tracer()
+        tracer = FlaskTracer(jaeger_tracer)
 
         @app.route('/log')
+        # Indicate that /log endpoint should be traced
         @tracer.trace()
         def log():
+                # Extract the span information for request object.
+                request_span = tracer.get_span(request)
+                # Start internal span to trace some kind of business logic for /log.
+                current_span = jaeger_tracer.start_span("python webserver internal span of log method",
+                                                        child_of=request_span)
+                # Perform some computations to be traced.
+
+                a = 1
+                b = 2
+                c = a + b
 
-                span_ctx = ls_tracer.extract(Format.HTTP_HEADERS, request.headers)
-                print(request.headers)
-                span_tags = {tags.SPAN_KIND: tags.SPAN_KIND_RPC_SERVER}
-                print(span_tags)
-                child_span = ls_tracer.start_span("python webserver internal span of log method",
-                                                  child_of=span_ctx,
-                                                  tags=span_tags)
-                #do some things here
-                child_span.finish()
+                # Finish the current span.
+                current_span.finish()
                 return "log"
 
         app.run(debug=True, host='0.0.0.0', port=5000)