Skip to content

Commit

Permalink
[docs] Added Running a Python app with Opentelemetry manual instrumen…
Browse files Browse the repository at this point in the history 
…tion (#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ć <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

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

Co-authored-by: Adnan Rahić <ado.raha198@gmail.com>

* 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ć <ado.raha198@gmail.com>
  • Loading branch information
@maheshkasabe @adnanrahic
maheshkasabe and adnanrahic committed Apr 21, 2023
1 parent 6fdb92d commit e8bce0a
Showing 1 changed file with 252 additions and 0 deletions.
252 changes: 252 additions & 0 deletions ...orials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md
View file
@@ -0,0 +1,252 @@
# Running a Python app with Opentelemetry manual instrumention
:::note
[Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-python)
:::

[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.

## Sample Python app with OpenTelemetry Collector and Tracetest

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.

## Prerequisites

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!

## Project structure

The project is built with Docker Compose. It contains two distinct `docker-compose.yaml` files.

### 1. Python app
The `docker-compose.yaml` file and `Dockerfile` in the root directory are for the Python app.

### 2. Tracetest
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.

The `tracetest` directory is self-contained and will run all the prerequisites for enabling OpenTelemetry traces and trace-based testing with Tracetest.

### Docker Compose Network
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.

## Python app

The Python app is a simple Flask app, contained in the `app.py` file.

The code below imports all the Flask, and OpenTelemetry libraries and configures both manual and automatic OpenTelemetry instrumentation.

```
from flask import Flask, request
import json
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)
```

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.

```python
app = Flask(__name__)

@app.route("/manual")
def manual():
with tracer.start_as_current_span(
"manual",
attributes={ "endpoint": "/manual", "foo": "bar" }
):
return "App works with a manual instrumentation."

@app.route('/automatic')
def automatic():
return "App works with automatic instrumentation."

@app.route("/")
def home():
return "App works."
```


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.

```Dockerfile
FROM python:3.10.1-slim
WORKDIR /opt/app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
RUN opentelemetry-bootstrap -a install
EXPOSE 8080
```

The `docker-compose.yaml` contains just one service for the Python app. The service is stared with the `command` parameter.

```yaml
version: '3'
services:
app:
image: quick-start-python
platform: linux/amd64
extra_hosts:
- "host.docker.internal:host-gateway"
build: .
ports:
- "8080:8080"
# using the command here instead of the Dockerfile
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
depends_on:
tracetest:
condition: service_started
```

To start it, run this command:

```bash
docker compose build # optional if you haven't already built the image
docker compose up
```

This will start the Python app. But, you're not sending the traces anywhere.

Let's fix this by configuring Tracetest and OpenTelemetry Collector.

## Tracetest

The `docker-compose.yaml` in the `tracetest` directory is configured with three services.

- **Postgres** - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests.
- [**OpenTelemetry Collector**](https://opentelemetry.io/docs/collector/) - A vendor-agnostic implementation of how to receive, process and export telemetry data.
- [**Tracetest**](https://tracetest.io/) - Trace-based testing that generates end-to-end tests automatically from traces.

```yaml
version: "3"
services:
tracetest:
image: kubeshop/tracetest:latest
platform: linux/amd64
volumes:
- type: bind
source: ./tracetest/tracetest-config.yaml
target: /app/tracetest.yaml
- type: bind
source: ./tracetest/tracetest-provision.yaml
target: /app/provisioning.yaml
ports:
- 11633:11633
command: --provisioning-file /app/provisioning.yaml
depends_on:
postgres:
condition: service_healthy
otel-collector:
condition: service_started
healthcheck:
test: ["CMD", "wget", "--spider", "localhost:11633"]
interval: 1s
timeout: 3s
retries: 60
environment:
TRACETEST_DEV: ${TRACETEST_DEV}

postgres:
image: postgres:14
environment:
POSTGRES_PASSWORD: postgres
POSTGRES_USER: postgres
healthcheck:
test: pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"
interval: 1s
timeout: 5s
retries: 60

otel-collector:
image: otel/opentelemetry-collector-contrib:0.59.0
command:
- "--config"
- "/otel-local-config.yaml"
volumes:
- ./tracetest/collector.config.yaml:/otel-local-config.yaml

```

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.


The `tracetest-config.yaml` file contains the basic setup of connecting Tracetest to the Postgres instance.

```yaml
postgres:
host: postgres
user: postgres
password: postgres
port: 5432
dbname: postgres
params: sslmode=disable

```

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.
```yaml

---
type: DataStore
spec:
name: OpenTelemetry Collector
type: otlp
isdefault: true
```

But how are traces sent to Tracetest?

The `collector.config.yaml` explains that. It receives traces via either `grpc` or `http`. Then, exports them to Tracetest's otlp endpoint `tracetest:21321`.

```yaml
receivers:
otlp:
protocols:
grpc:
http:

processors:
batch:
timeout: 100ms

exporters:
logging:
loglevel: debug
otlp/1:
endpoint: tracetest:21321
# Send traces to Tracetest.
# Read more in docs here: https://docs.tracetest.io/configuration/connecting-to-data-stores/opentelemetry-collector
tls:
insecure: true

service:
pipelines:
traces/1:
receivers: [otlp]
processors: [batch]
exporters: [otlp/1]

```

## Run both the Python app and Tracetest

To start both the Python app and Tracetest we will run this command:

```bash
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built already
```

This will start your Tracetest instance on `http://localhost:11633/`. Go ahead and open it up.

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.

## Learn more

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 comments on commit e8bce0a

Please sign in to comment.