Skip to content

Commit 348889d

Browse files
alrexc24t
alrex
authored and
c24t
committed
Adding more documentation around examples (open-telemetry#277)
1 parent 30a1bb8 commit 348889d

19 files changed

+377
-22
lines changed

‎README.md

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -95,11 +95,7 @@ exporter.export([(counter, label_values)])
9595
exporter.shutdown()
9696
```
9797

98-
See the [API
99-
documentation](https://open-telemetry.github.io/opentelemetry-python/) for more
100-
detail, and the
101-
[opentelemetry-example-app](./examples/opentelemetry-example-app/README.rst)
102-
for a complete example.
98+
See the [API documentation](https://open-telemetry.github.io/opentelemetry-python/) for more detail, and the [examples folder](./examples) for a more sample code.
10399

104100
## Contributing
105101

‎examples/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Examples
2+
This folder contains various examples to demonstrate using OpenTelemetry.
3+
4+
##### basic_tracer
5+
This example shows how to use OpenTelemetry to instrument an application - e.g. a batch job.
6+
7+
##### http
8+
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.
9+
10+
##### opentelemetry-example-app
11+
This package is a complete example of an application instrumented with OpenTelemetry.

‎examples/basic_tracer/README.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Overview
2+
3+
This example shows how to use OpenTelemetry to instrument a Python application - e.g. a batch job.
4+
It supports exporting spans either to the console or to [Jaeger](https://www.jaegertracing.io).
5+
6+
## Installation
7+
8+
```sh
9+
$ pip install opentelemetry-api opentelemetry-sdk
10+
```
11+
12+
Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
13+
14+
## Run the Application
15+
16+
### Console
17+
18+
* Run the sample
19+
20+
```bash
21+
$ # from this directory
22+
$ python tracer.py
23+
```
24+
25+
The output will be displayed at the console
26+
27+
```bash
28+
AsyncRuntimeContext({'current_span': Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}))})
29+
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)
30+
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)
31+
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)
32+
```
33+
34+
35+
### Jaeger
36+
37+
* Run the sample
38+
39+
```sh
40+
$ pip install opentelemetry-ext-jaeger
41+
$ # from this directory
42+
$ EXPORTER=jaeger python tracer.py
43+
```
44+
45+
#### Jaeger UI
46+
47+
Open the Jaeger UI in your browser [http://localhost:16686](http://localhost:16686)
48+
49+
<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
50+
Select `basic-service` under *Service Name* and click on *Find Traces*.
51+
52+
Click on the trace to view its details.
53+
54+
<p align="center"><img src="./images/jaeger-ui-detail.png?raw=true"/></p>
55+
56+
## Useful links
57+
- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
58+
- For more information on tracing in Python, visit: <https://github.com/open-telemetry/opentelemetry-python>
59+
60+
## LICENSE
61+
62+
Apache License 2.0

‎examples/basic_tracer/__init__.py

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# pylint: disable=C0103
2+
# Copyright 2019, OpenTelemetry Authors
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.

‎examples/basic_tracer/images/jaeger-ui-detail.png

120 KB
Loading

‎examples/basic_tracer/images/jaeger-ui.png

251 KB
Loading

‎examples/basic_tracer/tests/__init__.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Copyright 2019, OpenTelemetry Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.

‎examples/basic_tracer/tests/test_tracer.py

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Copyright 2019, OpenTelemetry Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
import os
15+
import subprocess
16+
import unittest
17+
18+
19+
class TestBasicTracerExample(unittest.TestCase):
20+
def test_basic_tracer(self):
21+
dirpath = os.path.dirname(os.path.realpath(__file__))
22+
test_script = "{}/../tracer.py".format(dirpath)
23+
output = subprocess.check_output(test_script).decode()
24+
25+
self.assertIn('name="foo"', output)
26+
self.assertIn('name="bar"', output)
27+
self.assertIn('name="baz"', output)

‎examples/basic_tracer/tracer.py

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Copyright 2019, OpenTelemetry Authors
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
import os
18+
19+
from opentelemetry import trace
20+
from opentelemetry.context import Context
21+
from opentelemetry.sdk.trace import Tracer
22+
from opentelemetry.sdk.trace.export import (
23+
BatchExportSpanProcessor,
24+
ConsoleSpanExporter,
25+
)
26+
27+
if os.getenv("EXPORTER") == "jaeger":
28+
from opentelemetry.ext.jaeger import JaegerSpanExporter
29+
30+
exporter = JaegerSpanExporter(
31+
service_name="basic-service",
32+
agent_host_name="localhost",
33+
agent_port=6831,
34+
)
35+
else:
36+
exporter = ConsoleSpanExporter()
37+
38+
# The preferred tracer implementation must be set, as the opentelemetry-api
39+
# defines the interface with a no-op implementation.
40+
trace.set_preferred_tracer_implementation(lambda T: Tracer())
41+
tracer = trace.tracer()
42+
43+
# SpanExporter receives the spans and send them to the target location.
44+
span_processor = BatchExportSpanProcessor(exporter)
45+
46+
tracer.add_span_processor(span_processor)
47+
with tracer.start_as_current_span("foo"):
48+
with tracer.start_as_current_span("bar"):
49+
with tracer.start_as_current_span("baz"):
50+
print(Context)
51+
52+
span_processor.shutdown()

‎examples/http/README.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Overview
2+
3+
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.
4+
It supports exporting spans either to the console or to [Jaeger](https://www.jaegertracing.io).
5+
6+
## Installation
7+
8+
```sh
9+
$ pip install opentelemetry-api opentelemetry-sdk opentelemetry-ext-wsgi opentelemetry-ext-http-requests
10+
```
11+
12+
Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
13+
14+
## Run the Application
15+
16+
### Console
17+
18+
* Run the server
19+
20+
```bash
21+
$ # from this directory
22+
$ python server.py
23+
```
24+
25+
* Run the client from a different terminal
26+
27+
```bash
28+
$ # from this directory
29+
$ python tracer_client.py
30+
```
31+
32+
The output will be displayed at the console on the client side
33+
34+
```bash
35+
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)
36+
```
37+
38+
And on the server
39+
40+
```bash
41+
127.0.0.1 - - [07/Nov/2019 13:53:00] "GET / HTTP/1.1" 200 -
42+
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)
43+
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)
44+
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)
45+
```
46+
47+
### Jaeger
48+
49+
* Run the server
50+
51+
```sh
52+
$ pip install opentelemetry-ext-jaeger
53+
$ # from this directory
54+
$ EXPORTER=jaeger python server.py
55+
```
56+
57+
* Run the client from a different terminal
58+
59+
```bash
60+
$ EXPORTER=jaeger python tracer_client.py
61+
```
62+
63+
#### Jaeger UI
64+
65+
Open the Jaeger UI in your browser [http://localhost:16686](http://localhost:16686)
66+
67+
<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
68+
Select `http-server` under *Service Name* and click on *Find Traces*.
69+
70+
Click on the trace to view its details.
71+
72+
<p align="center"><img src="./images/jaeger-ui-detail.png?raw=true"/></p>
73+
74+
## Useful links
75+
- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
76+
- For more information on tracing in Python, visit: <https://github.com/open-telemetry/opentelemetry-python>
77+
78+
## LICENSE
79+
80+
Apache License 2.0

‎examples/http/__init__.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Copyright 2019, OpenTelemetry Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.

‎examples/http/images/jaeger-ui-detail.png

141 KB
Loading

‎examples/http/images/jaeger-ui.png

229 KB
Loading

‎examples/http/requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
flask

‎examples/trace/server.py renamed to ‎examples/http/server.py

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414
# See the License for the specific language governing permissions and
1515
# limitations under the License.
1616

17+
import os
18+
1719
import flask
1820
import requests
1921

@@ -22,30 +24,41 @@
2224
from opentelemetry.ext.wsgi import OpenTelemetryMiddleware
2325
from opentelemetry.sdk.trace import Tracer
2426
from opentelemetry.sdk.trace.export import (
27+
BatchExportSpanProcessor,
2528
ConsoleSpanExporter,
26-
SimpleExportSpanProcessor,
2729
)
2830

31+
if os.getenv("EXPORTER") == "jaeger":
32+
from opentelemetry.ext.jaeger import JaegerSpanExporter
33+
34+
exporter = JaegerSpanExporter(
35+
service_name="http-server",
36+
agent_host_name="localhost",
37+
agent_port=6831,
38+
)
39+
else:
40+
exporter = ConsoleSpanExporter()
41+
2942
# The preferred tracer implementation must be set, as the opentelemetry-api
3043
# defines the interface with a no-op implementation.
3144
trace.set_preferred_tracer_implementation(lambda T: Tracer())
45+
tracer = trace.tracer()
46+
47+
# SpanExporter receives the spans and send them to the target location.
48+
span_processor = BatchExportSpanProcessor(exporter)
49+
tracer.add_span_processor(span_processor)
3250

3351
# Integrations are the glue that binds the OpenTelemetry API and the
3452
# frameworks and libraries that are used together, automatically creating
3553
# Spans and propagating context as appropriate.
36-
http_requests.enable(trace.tracer())
37-
38-
# SpanExporter receives the spans and send them to the target location.
39-
span_processor = SimpleExportSpanProcessor(ConsoleSpanExporter())
40-
trace.tracer().add_span_processor(span_processor)
41-
54+
http_requests.enable(tracer)
4255
app = flask.Flask(__name__)
4356
app.wsgi_app = OpenTelemetryMiddleware(app.wsgi_app)
4457

4558

4659
@app.route("/")
4760
def hello():
48-
with trace.tracer().start_as_current_span("parent"):
61+
with tracer.start_as_current_span("parent"):
4962
requests.get("https://www.wikipedia.org/wiki/Rabbit")
5063
return "hello"
5164

‎examples/http/tests/__init__.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Copyright 2019, OpenTelemetry Authors
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.

0 commit comments

Comments
 (0)