Skip to content

Commit 0889895

Browse files
mauriciovasquezbernalmauriciovasquezbernal
authored
docs: Fix autoinstrumentation docs (#544)
- Convert file to rst to be included in the generated documentation - Include docs for main module. - Use internal reference instead of read the docs link
1 parent b5b297c commit 0889895

File tree

3 files changed

+198
-1
lines changed

3 files changed

+198
-1
lines changed

‎docs/auto_instrumentation/auto_instrumentation.rst

+8
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
OpenTelemetry Python Autoinstrumentation
22
========================================
33

4+
.. automodule:: opentelemetry.auto_instrumentation
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
9+
Submodules
10+
----------
11+
412
.. toctree::
513
:maxdepth: 1
614

‎docs/examples/auto-instrumentation/README.rst

+189
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
Autoinstrumentation
2+
===================
3+
4+
Overview
5+
--------
6+
7+
This example shows how to use auto-instrumentation in OpenTelemetry.
8+
This example is also based on a previous example for OpenTracing that
9+
can be found
10+
`here <https://github.com/yurishkuro/opentracing-tutorial/tree/master/python>`__.
11+
12+
The source files of these examples are available :scm_web:`here <docs/examples/auto-instrumentation/>`.
13+
14+
This example uses 2 scripts whose main difference is they being
15+
instrumented manually or not:
16+
17+
1. ``server_instrumented.py`` which has been instrumented manually
18+
2. ``server_uninstrumented.py`` which has not been instrumented manually
19+
20+
The former will be run without the automatic instrumentation agent and
21+
the latter with the automatic instrumentation agent. They should produce
22+
the same result, showing that the automatic instrumentation agent does
23+
the equivalent of what manual instrumentation does.
24+
25+
In order to understand this better, here is the relevant part of both
26+
scripts:
27+
28+
Manually instrumented server
29+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
30+
31+
``server_instrumented.py``
32+
33+
.. code:: python
34+
35+
@app.route("/server_request")
36+
def server_request():
37+
with tracer.start_as_current_span(
38+
"server_request",
39+
parent=propagators.extract(
40+
lambda dict_, key: dict_.get(key, []), request.headers
41+
)["current-span"],
42+
):
43+
print(request.args.get("param"))
44+
return "served"
45+
46+
Publisher not instrumented manually
47+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
48+
49+
``server_uninstrumented.py``
50+
51+
.. code:: python
52+
53+
@app.route("/server_request")
54+
def server_request():
55+
print(request.args.get("param"))
56+
return "served"
57+
58+
Preparation
59+
-----------
60+
61+
This example will be executed in a separate virtual environment:
62+
63+
.. code:: sh
64+
65+
$ mkdir auto_instrumentation
66+
$ virtualenv auto_instrumentation
67+
$ source auto_instrumentation/bin/activate
68+
69+
Installation
70+
------------
71+
72+
.. code:: sh
73+
74+
$ pip install opentelemetry-sdk
75+
$ pip install opentelemetry-auto-instrumentation
76+
$ pip install opentelemetry-ext-flask
77+
$ pip install requests
78+
79+
Execution
80+
---------
81+
82+
Execution of the manually instrumented server
83+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
This is done in 2 separate consoles, one to run each of the scripts that
86+
make up this example:
87+
88+
.. code:: sh
89+
90+
$ source auto_instrumentation/bin/activate
91+
$ python server_instrumented.py
92+
93+
.. code:: sh
94+
95+
$ source auto_instrumentation/bin/activate
96+
$ python client.py testing
97+
98+
The execution of ``server_instrumented.py`` should return an output
99+
similar to:
100+
101+
.. code:: sh
102+
103+
{
104+
"name": "server_request",
105+
"context": {
106+
"trace_id": "0xfa002aad260b5f7110db674a9ddfcd23",
107+
"span_id": "0x8b8bbaf3ca9c5131",
108+
"trace_state": "{}"
109+
},
110+
"kind": "SpanKind.SERVER",
111+
"parent_id": null,
112+
"start_time": "2020-04-30T17:28:57.886397Z",
113+
"end_time": "2020-04-30T17:28:57.886490Z",
114+
"status": {
115+
"canonical_code": "OK"
116+
},
117+
"attributes": {
118+
"component": "http",
119+
"http.method": "GET",
120+
"http.server_name": "127.0.0.1",
121+
"http.scheme": "http",
122+
"host.port": 8082,
123+
"http.host": "localhost:8082",
124+
"http.target": "/server_request?param=testing",
125+
"net.peer.ip": "127.0.0.1",
126+
"net.peer.port": 52872,
127+
"http.flavor": "1.1"
128+
},
129+
"events": [],
130+
"links": []
131+
}
132+
133+
Execution of an automatically instrumented server
134+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135+
136+
Now, kill the execution of ``server_instrumented.py`` with ``ctrl + c``
137+
and run this instead:
138+
139+
.. code:: sh
140+
141+
$ opentelemetry-auto-instrumentation python server_uninstrumented.py
142+
143+
In the console where you previously executed ``client.py``, run again
144+
this again:
145+
146+
.. code:: sh
147+
148+
$ python client.py testing
149+
150+
The execution of ``server_uninstrumented.py`` should return an output
151+
similar to:
152+
153+
.. code:: sh
154+
155+
{
156+
"name": "server_request",
157+
"context": {
158+
"trace_id": "0x9f528e0b76189f539d9c21b1a7a2fc24",
159+
"span_id": "0xd79760685cd4c269",
160+
"trace_state": "{}"
161+
},
162+
"kind": "SpanKind.SERVER",
163+
"parent_id": "0xb4fb7eee22ef78e4",
164+
"start_time": "2020-04-30T17:10:02.400604Z",
165+
"end_time": "2020-04-30T17:10:02.401858Z",
166+
"status": {
167+
"canonical_code": "OK"
168+
},
169+
"attributes": {
170+
"component": "http",
171+
"http.method": "GET",
172+
"http.server_name": "127.0.0.1",
173+
"http.scheme": "http",
174+
"host.port": 8082,
175+
"http.host": "localhost:8082",
176+
"http.target": "/server_request?param=testing",
177+
"net.peer.ip": "127.0.0.1",
178+
"net.peer.port": 48240,
179+
"http.flavor": "1.1",
180+
"http.route": "/server_request",
181+
"http.status_text": "OK",
182+
"http.status_code": 200
183+
},
184+
"events": [],
185+
"links": []
186+
}
187+
188+
Both outputs are equivalent since the automatic instrumentation does
189+
what the manual instrumentation does too.

‎opentelemetry-auto-instrumentation/src/opentelemetry/auto_instrumentation/__init__.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -24,5 +24,5 @@
2424
2525
The code in ``program.py`` needs to use one of the packages for which there is
2626
an OpenTelemetry integration. For a list of the available integrations please
27-
check `here <https://opentelemetry-python.readthedocs.io/>`_.
27+
check :doc:`here <../../index>`.
2828
"""

0 commit comments

Comments
 (0)