Skip to content

Commit e8bce0a

Browse files
maheshkasabeadnanrahic
maheshkasabe
and
adnanrahic
authored
[docs] Added Running a Python app with Opentelemetry manual instrumention (#2380)
* [docs]Added Running a Python app with Opentelemetry manual instrumention * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md Co-authored-by: Adnan Rahić <[email protected]> * Update running-python-app-with-opentelemetry-collector-and-tracetest.md * Update running-python-app-with-opentelemetry-collector-and-tracetest.md --------- Co-authored-by: Adnan Rahić <[email protected]>
1 parent 6fdb92d commit e8bce0a

File tree

1 file changed

+252
-0
lines changed

1 file changed

+252
-0
lines changed

‎docs/docs/examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Running a Python app with Opentelemetry manual instrumention
2+
:::note
3+
[Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-python)
4+
:::
5+
6+
[Tracetest](https://tracetest.io/) is a testing tool based on [OpenTelemetry](https://opentelemetry.io/) that allows you to test your distributed application. It allows you to use your telemetry data generated by the OpenTelemetry tools to check and assert if your application has the desired behavior defined by your test definitions.
7+
8+
## Sample Python app with OpenTelemetry Collector and Tracetest
9+
10+
This is a simple quick start on how to configure a Python app to use OpenTelemetry instrumentation with traces, and Tracetest for enhancing your e2e and integration tests with trace-based testing.
11+
12+
## Prerequisites
13+
14+
You will need [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your machine to run this quick start app!
15+
16+
## Project structure
17+
18+
The project is built with Docker Compose. It contains two distinct `docker-compose.yaml` files.
19+
20+
### 1. Python app
21+
The `docker-compose.yaml` file and `Dockerfile` in the root directory are for the Python app.
22+
23+
### 2. Tracetest
24+
The `docker-compose.yaml` file, `collector.config.yaml`, `tracetest-provision.yaml`, and `tracetest-config.yaml` in the `tracetest` directory are for setting up Tracetest and the OpenTelemetry Collector.
25+
26+
The `tracetest` directory is self-contained and will run all the prerequisites for enabling OpenTelemetry traces and trace-based testing with Tracetest.
27+
28+
### Docker Compose Network
29+
All `services` in the `docker-compose.yaml` are on the same network and will be reachable by hostname from within other services. E.g. `tracetest:21321` in the `collector.config.yaml` will map to the `tracetest` service, where the port `21321` is the port where Tracetest accepts traces.
30+
31+
## Python app
32+
33+
The Python app is a simple Flask app, contained in the `app.py` file.
34+
35+
The code below imports all the Flask, and OpenTelemetry libraries and configures both manual and automatic OpenTelemetry instrumentation.
36+
37+
```
38+
from flask import Flask, request
39+
import json
40+
41+
from opentelemetry import trace
42+
from opentelemetry.sdk.resources import Resource
43+
from opentelemetry.sdk.trace import TracerProvider
44+
from opentelemetry.sdk.trace.export import BatchSpanProcessor
45+
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
46+
47+
provider = TracerProvider()
48+
processor = BatchSpanProcessor(ConsoleSpanExporter())
49+
provider.add_span_processor(processor)
50+
trace.set_tracer_provider(provider)
51+
tracer = trace.get_tracer(__name__)
52+
```
53+
54+
There are 3 endpoints in the Flask app. For seeing manual instrumentation trigger the `"/manual"` endpoint. For seeing the automatic instrumentation trigger the `"/automatic"` endpoint respectively.
55+
56+
```python
57+
app = Flask(__name__)
58+
59+
@app.route("/manual")
60+
def manual():
61+
with tracer.start_as_current_span(
62+
"manual",
63+
attributes={ "endpoint": "/manual", "foo": "bar" }
64+
):
65+
return "App works with a manual instrumentation."
66+
67+
@app.route('/automatic')
68+
def automatic():
69+
return "App works with automatic instrumentation."
70+
71+
@app.route("/")
72+
def home():
73+
return "App works."
74+
```
75+
76+
77+
The `Dockerfile` includes bootstrapping the needed OpenTelemetry packages. As you can see it does not have the `CMD` command. Instead, it's configured in the `docker-compose.yaml` below.
78+
79+
```Dockerfile
80+
FROM python:3.10.1-slim
81+
WORKDIR /opt/app
82+
COPY . .
83+
RUN pip install --no-cache-dir -r requirements.txt
84+
RUN opentelemetry-bootstrap -a install
85+
EXPOSE 8080
86+
```
87+
88+
The `docker-compose.yaml` contains just one service for the Python app. The service is stared with the `command` parameter.
89+
90+
```yaml
91+
version: '3'
92+
services:
93+
app:
94+
image: quick-start-python
95+
platform: linux/amd64
96+
extra_hosts:
97+
- "host.docker.internal:host-gateway"
98+
build: .
99+
ports:
100+
- "8080:8080"
101+
# using the command here instead of the Dockerfile
102+
command: opentelemetry-instrument --traces_exporter otlp --service_name app --exporter_otlp_endpoint otel-collector:4317 --exporter_otlp_insecure true flask run --host=0.0.0.0 --port=8080
103+
depends_on:
104+
tracetest:
105+
condition: service_started
106+
```
107+
108+
To start it, run this command:
109+
110+
```bash
111+
docker compose build # optional if you haven't already built the image
112+
docker compose up
113+
```
114+
115+
This will start the Python app. But, you're not sending the traces anywhere.
116+
117+
Let's fix this by configuring Tracetest and OpenTelemetry Collector.
118+
119+
## Tracetest
120+
121+
The `docker-compose.yaml` in the `tracetest` directory is configured with three services.
122+
123+
- **Postgres** - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests.
124+
- [**OpenTelemetry Collector**](https://opentelemetry.io/docs/collector/) - A vendor-agnostic implementation of how to receive, process and export telemetry data.
125+
- [**Tracetest**](https://tracetest.io/) - Trace-based testing that generates end-to-end tests automatically from traces.
126+
127+
```yaml
128+
version: "3"
129+
services:
130+
tracetest:
131+
image: kubeshop/tracetest:latest
132+
platform: linux/amd64
133+
volumes:
134+
- type: bind
135+
source: ./tracetest/tracetest-config.yaml
136+
target: /app/tracetest.yaml
137+
- type: bind
138+
source: ./tracetest/tracetest-provision.yaml
139+
target: /app/provisioning.yaml
140+
ports:
141+
- 11633:11633
142+
command: --provisioning-file /app/provisioning.yaml
143+
depends_on:
144+
postgres:
145+
condition: service_healthy
146+
otel-collector:
147+
condition: service_started
148+
healthcheck:
149+
test: ["CMD", "wget", "--spider", "localhost:11633"]
150+
interval: 1s
151+
timeout: 3s
152+
retries: 60
153+
environment:
154+
TRACETEST_DEV: ${TRACETEST_DEV}
155+
156+
postgres:
157+
image: postgres:14
158+
environment:
159+
POSTGRES_PASSWORD: postgres
160+
POSTGRES_USER: postgres
161+
healthcheck:
162+
test: pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"
163+
interval: 1s
164+
timeout: 5s
165+
retries: 60
166+
167+
otel-collector:
168+
image: otel/opentelemetry-collector-contrib:0.59.0
169+
command:
170+
- "--config"
171+
- "/otel-local-config.yaml"
172+
volumes:
173+
- ./tracetest/collector.config.yaml:/otel-local-config.yaml
174+
175+
```
176+
177+
Tracetest depends on both Postgres and the OpenTelemetry Collector. Both Tracetest and the OpenTelemetry Collector require config files to be loaded via a volume. The volumes are mapped from the root directory into the `tracetest` directory and the respective config files.
178+
179+
180+
The `tracetest-config.yaml` file contains the basic setup of connecting Tracetest to the Postgres instance.
181+
182+
```yaml
183+
postgres:
184+
host: postgres
185+
user: postgres
186+
password: postgres
187+
port: 5432
188+
dbname: postgres
189+
params: sslmode=disable
190+
191+
```
192+
193+
The `tracetest-provision.yaml` file provisions the trace data store and polling to store in the Postgres database. The data store is set to OTLP meaning the traces will be stored in Tracetest itself.
194+
```yaml
195+
196+
---
197+
type: DataStore
198+
spec:
199+
name: OpenTelemetry Collector
200+
type: otlp
201+
isdefault: true
202+
```
203+
204+
But how are traces sent to Tracetest?
205+
206+
The `collector.config.yaml` explains that. It receives traces via either `grpc` or `http`. Then, exports them to Tracetest's otlp endpoint `tracetest:21321`.
207+
208+
```yaml
209+
receivers:
210+
otlp:
211+
protocols:
212+
grpc:
213+
http:
214+
215+
processors:
216+
batch:
217+
timeout: 100ms
218+
219+
exporters:
220+
logging:
221+
loglevel: debug
222+
otlp/1:
223+
endpoint: tracetest:21321
224+
# Send traces to Tracetest.
225+
# Read more in docs here: https://docs.tracetest.io/configuration/connecting-to-data-stores/opentelemetry-collector
226+
tls:
227+
insecure: true
228+
229+
service:
230+
pipelines:
231+
traces/1:
232+
receivers: [otlp]
233+
processors: [batch]
234+
exporters: [otlp/1]
235+
236+
```
237+
238+
## Run both the Python app and Tracetest
239+
240+
To start both the Python app and Tracetest we will run this command:
241+
242+
```bash
243+
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built already
244+
```
245+
246+
This will start your Tracetest instance on `http://localhost:11633/`. Go ahead and open it up.
247+
248+
Start creating tests! Make sure to use the `http://app:8080/` url in your test creation, because your Python app and Tracetest are in the same network.
249+
250+
## Learn more
251+
252+
Feel free to check out our [examples in GitHub](https://github.com/kubeshop/tracetest/tree/main/examples), and join our [Discord Community](https://discord.gg/8MtcMrQNbX) for more info!

0 commit comments

Comments
 (0)