Adding more documentation around examples

examples/basic-tracer/README.md

@@ -0,0 +1,62 @@
+# Overview
+
+This example shows how to use OpenTelemetry to instrument a Python application - e.g. a batch job.
+It supports exporting spans either to the console or to [Jaeger](https://www.jaegertracing.io).
+
+## Installation
+
+```sh
+$ pip install opentelemetry-api opentelemetry-sdk
+```
+
+Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
+
+## Run the Application
+
+### Console
+
+* Run the sample
+
+```bash
+$ # from this directory
+$ python tracer.py
+```
+
+The output will be displayed at the console
+
+```bash
+AsyncRuntimeContext({'current_span': Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}))})
+Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={})), start_time=2019-11-07T21:26:45.934412Z, end_time=2019-11-07T21:26:45.934567Z)
+Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={})), start_time=2019-11-07T21:26:45.934396Z, end_time=2019-11-07T21:26:45.934576Z)
+Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={}), kind=SpanKind.INTERNAL, parent=None, start_time=2019-11-07T21:26:45.934369Z, end_time=2019-11-07T21:26:45.934580Z)
+```
+
+
+### Jaeger
+
+* Run the sample
+
+```sh
+$ pip install opentelemetry-ext-jaeger
+$ # from this directory
+$ EXPORTER=jaeger python tracer.py
+```
+
+#### Jaeger UI
+
+Open the Jaeger UI in your browser [http://localhost:16686](http://localhost:16686)
+
+<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
+Select `basic-service` under *Service Name* and click on *Find Traces*.
+
+Click on the trace to view its details.
+
+<p align="center"><img src="./images/jaeger-ui-detail.png?raw=true"/></p>
+
+## Useful links
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on tracing in Python, visit: <https://github.com/open-telemetry/opentelemetry-python>
+
+## LICENSE
+
+Apache License 2.0

examples/basic-tracer/tracer.py

@@ -0,0 +1,30 @@
+import os
+
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.ext.jaeger import JaegerSpanExporter
+from opentelemetry.sdk.trace import Tracer
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter
+from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+trace.set_preferred_tracer_implementation(lambda T: Tracer())
+tracer = trace.tracer()
+
+if os.getenv("EXPORTER") == "jaeger":
+    exporter = JaegerSpanExporter(
+        service_name="basic-service",
+        agent_host_name="localhost",
+        agent_port=6831,
+    )
+else:
+    exporter = ConsoleSpanExporter()
+
+span_processor = BatchExportSpanProcessor(exporter)
+
+tracer.add_span_processor(span_processor)
+with tracer.start_as_current_span("foo"):
+    with tracer.start_as_current_span("bar"):
+        with tracer.start_as_current_span("baz"):
+            print(Context)
+
+span_processor.shutdown()

examples/http/README.md

@@ -0,0 +1,79 @@
+# Overview
+
+This example shows how to use [OpenTelemetryMiddleware](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-wsgi) and [requests](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-http-requests) integrations to instrument a client and a server in Python.
+It supports exporting spans either to the console or to [Jaeger](https://www.jaegertracing.io).
+
+## Installation
+
+```sh
+$ pip install opentelemetry-api opentelemetry-sdk opentelemetry-ext-wsgi opentelemetry-ext-http-requests
+```
+
+Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
+
+## Run the Application
+
+### Console
+
+* Run the server
+
+```bash
+$ # from this directory
+$ python server.py
+```
+
+* Run the client from a different terminal
+
+```bash
+$ # from this directory
+$ python client.py
+```
+
+The output will be displayed at the console on the client side
+
+```bash
+Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), kind=SpanKind.CLIENT, parent=None, start_time=2019-11-07T21:52:59.591634Z, end_time=2019-11-07T21:53:00.386014Z)
+```
+
+And on the server
+
+```bash
+127.0.0.1 - - [07/Nov/2019 13:53:00] "GET / HTTP/1.1" 200 -
+Span(name="/wiki/Rabbit", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x4bf0be462b91d6ef, trace_state={}), kind=SpanKind.CLIENT, parent=Span(name="parent", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x68338643ccb2d53b, trace_state={})), start_time=2019-11-07T21:52:59.601597Z, end_time=2019-11-07T21:53:00.380491Z)
+Span(name="parent", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x68338643ccb2d53b, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={})), start_time=2019-11-07T21:52:59.601233Z, end_time=2019-11-07T21:53:00.384485Z)
+Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={}), kind=SpanKind.SERVER, parent=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), start_time=2019-11-07T21:52:59.600816Z, end_time=2019-11-07T21:53:00.385322Z)
+```
+
+### Jaeger
+
+* Run the server
+
+```sh
+$ pip install opentelemetry-ext-jaeger
+$ # from this directory
+$ EXPORTER=jaeger python server.py
+```
+
+* Run the client from a different terminal
+
+```bash
+$ EXPORTER=jaeger python client.py
+```
+
+#### Jaeger UI
+
+Open the Jaeger UI in your browser [http://localhost:16686](http://localhost:16686)
+
+<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
+Select `http-server` under *Service Name* and click on *Find Traces*.
+
+Click on the trace to view its details.
+
+<p align="center"><img src="./images/jaeger-ui-detail.png?raw=true"/></p>
+## Useful links
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on tracing in Python, visit: <https://github.com/open-telemetry/opentelemetry-python>
+
+## LICENSE
+
+Apache License 2.0

examples/http/client.py

@@ -0,0 +1,28 @@
+import os
+import requests
+
+from opentelemetry import trace
+from opentelemetry.ext import http_requests
+from opentelemetry.ext.jaeger import JaegerSpanExporter
+from opentelemetry.sdk.trace import Tracer
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter
+from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+trace.set_preferred_tracer_implementation(lambda T: Tracer())
+tracer = trace.tracer()
+
+if os.getenv("EXPORTER") == "jaeger":
+    exporter = JaegerSpanExporter(
+        service_name="http-client",
+        agent_host_name="localhost",
+        agent_port=6831,
+    )
+else:
+    exporter = ConsoleSpanExporter()
+
+span_processor = BatchExportSpanProcessor(exporter)
+tracer.add_span_processor(span_processor)
+
+http_requests.enable(tracer)
+response = requests.get(url="http://127.0.0.1:5000/")
+span_processor.shutdown()

examples/http/server.py

@@ -0,0 +1,42 @@
+import flask
+import os
+import requests
+
+from opentelemetry import trace
+from opentelemetry.ext import http_requests
+from opentelemetry.ext.jaeger import JaegerSpanExporter
+from opentelemetry.ext.wsgi import OpenTelemetryMiddleware
+from opentelemetry.sdk.trace import Tracer
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter
+from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+trace.set_preferred_tracer_implementation(lambda T: Tracer())
+tracer = trace.tracer()
+
+if os.getenv("EXPORTER") == "jaeger":
+    exporter = JaegerSpanExporter(
+        service_name="http-server",
+        agent_host_name="localhost",
+        agent_port=6831,
+    )
+else:
+    exporter = ConsoleSpanExporter()
+
+span_processor = BatchExportSpanProcessor(exporter)
+tracer.add_span_processor(span_processor)
+
+http_requests.enable(tracer)
+app = flask.Flask(__name__)
+app.wsgi_app = OpenTelemetryMiddleware(app.wsgi_app)
+
+
+@app.route("/")
+def hello():
+    with tracer.start_as_current_span("parent"):
+        requests.get("https://www.wikipedia.org/wiki/Rabbit")
+    return "hello"
+
+
+if __name__ == "__main__":
+    app.run(debug=True)
+    span_processor.shutdown()