Skip to content

Commit 4f3c5b5

Browse files
tammy-baylis-swichalintiffany76opentelemetrybot
authored
Add "Troubleshooting" page to Python zero code section (#7036)
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com> Co-authored-by: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com>
1 parent 946b536 commit 4f3c5b5

File tree

2 files changed

+115
-66
lines changed

2 files changed

+115
-66
lines changed

‎content/en/docs/zero-code/python/_index.md

Lines changed: 10 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Python zero-code instrumentation
33
linkTitle: Python
44
weight: 30
55
aliases: [/docs/languages/python/automatic]
6-
cSpell:ignore: devel distro myapp
6+
cSpell:ignore: distro myapp
77
---
88

99
Automatic instrumentation with Python uses a Python agent that can be attached
@@ -45,6 +45,13 @@ Running `opentelemetry-bootstrap` without arguments lists the recommended
4545
instrumentation libraries to be installed. For more information, see
4646
[`opentelemetry-bootstrap`](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/opentelemetry-instrumentation#opentelemetry-bootstrap).
4747

48+
{{% alert title="Using <code>uv</code>?" color="warning" %}} If you are using
49+
the [uv](https://docs.astral.sh/uv/) package manager, you might face some
50+
difficulty when running `opentelemetry-bootstrap -a install`. For details, see
51+
[Bootstrap using uv](troubleshooting/#bootstrap-using-uv). {{% /alert %}}
52+
53+
{#configuring-the-agent}
54+
4855
## Configuring the agent
4956

5057
The agent is highly configurable.
@@ -86,68 +93,5 @@ For the full list, see the
8693

8794
## Troubleshooting
8895

89-
### Python package installation failure
90-
91-
The Python package installs require `gcc` and `gcc-c++`, which you may need to
92-
install if you’re running a slim version of Linux, such as CentOS.
93-
94-
<!-- markdownlint-disable blanks-around-fences -->
95-
96-
- CentOS
97-
```sh
98-
yum -y install python3-devel
99-
yum -y install gcc-c++
100-
```
101-
- Debian/Ubuntu
102-
```sh
103-
apt install -y python3-dev
104-
apt install -y build-essential
105-
```
106-
- Alpine
107-
```sh
108-
apk add python3-dev
109-
apk add build-base
110-
```
111-
112-
### gRPC Connectivity
113-
114-
To debug Python gRPC connectivity issues, set the following gRPC debug
115-
environment variables:
116-
117-
```sh
118-
export GRPC_VERBOSITY=debug
119-
export GRPC_TRACE=http,call_error,connectivity_state
120-
opentelemetry-instrument python YOUR_APP.py
121-
```
122-
123-
### Bootstrap using uv
124-
125-
When using the [uv](https://docs.astral.sh/uv/) package manager, you might face
126-
some difficulty when running `opentelemetry-bootstrap -a install`.
127-
128-
Instead, you can generate the requirements dynamically and install them using
129-
`uv`.
130-
131-
First, install the appropriate packages (or add them to your project file and
132-
run `uv sync`):
133-
134-
```sh
135-
uv pip install opentelemetry-distro opentelemetry-exporter-otlp
136-
```
137-
138-
Now, you can install the auto instrumentation:
139-
140-
```sh
141-
uv run opentelemetry-bootstrap -a requirements | uv pip install --requirement -
142-
```
143-
144-
Finally, use `uv run` to start your application (see
145-
[Configuring the agent](#configuring-the-agent)):
146-
147-
```sh
148-
uv run opentelemetry-instrument python myapp.py
149-
```
150-
151-
Please note that you have to reinstall the auto instrumentation every time you
152-
run `uv sync` or update existing packages. It is therefore recommended to make
153-
the installation part of your build pipeline.
96+
For general troubleshooting steps and solutions to specific issues, see
97+
[Troubleshooting](./troubleshooting/).

‎content/en/docs/zero-code/python/troubleshooting.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: Troubleshooting Python automatic instrumentation issues
3+
linkTitle: Troubleshooting
4+
weight: 40
5+
---
6+
7+
## Installation issues
8+
9+
### Python package installation failure
10+
11+
The Python package installs require `gcc` and `gcc-c++`, which you may need to
12+
install if you’re running a slim version of Linux, such as CentOS.
13+
14+
<!-- markdownlint-disable blanks-around-fences -->
15+
16+
{{< tabpane text=true >}} {{% tab "CentOS" %}}
17+
18+
```sh
19+
yum -y install python3-devel
20+
yum -y install gcc-c++
21+
```
22+
23+
{{% /tab %}} {{% tab "Debian/Ubuntu" %}}
24+
25+
```sh
26+
apt install -y python3-dev
27+
apt install -y build-essential
28+
```
29+
30+
{{% /tab %}} {{% tab "Alpine" %}}
31+
32+
```sh
33+
apk add python3-dev
34+
apk add build-base
35+
```
36+
37+
{{% /tab %}} {{< /tabpane >}}
38+
39+
{#bootstrap-using-uv}
40+
41+
### Bootstrap using uv
42+
43+
Running `opentelemetry-bootstrap -a install` when using the
44+
[uv](https://docs.astral.sh/uv/) package manager may result in errored or
45+
unexpected dependency setups.
46+
47+
Instead, you can generate OpenTelemetry requirements dynamically and install
48+
them using `uv`.
49+
50+
First, install the appropriate packages (or add them to your project file and
51+
run `uv sync`):
52+
53+
```sh
54+
uv pip install opentelemetry-distro opentelemetry-exporter-otlp
55+
```
56+
57+
Now, you can install the auto instrumentation:
58+
59+
```sh
60+
uv run opentelemetry-bootstrap -a requirements | uv pip install --requirement -
61+
```
62+
63+
Finally, use `uv run` to start your application (see
64+
[Configuring the agent](/docs/zero-code/python/#configuring-the-agent)):
65+
66+
```sh
67+
uv run opentelemetry-instrument python myapp.py
68+
```
69+
70+
Please note that you have to reinstall the auto instrumentation every time you
71+
run `uv sync` or update existing packages. It is therefore recommended to make
72+
the installation part of your build pipeline.
73+
74+
## Instrumentation issues
75+
76+
### Flask debug mode with reloader breaks instrumentation
77+
78+
The debug mode can be enabled in the Flask app like this:
79+
80+
```python
81+
if __name__ == "__main__":
82+
app.run(port=8082, debug=True)
83+
```
84+
85+
The debug mode can break instrumentation from happening because it enables a
86+
reloader. To run instrumentation while the debug mode is enabled, set the
87+
`use_reloader` option to `False`:
88+
89+
```python
90+
if __name__ == "__main__":
91+
app.run(port=8082, debug=True, use_reloader=False)
92+
```
93+
94+
## Connectivity issues
95+
96+
### gRPC Connectivity
97+
98+
To debug Python gRPC connectivity issues, set the following gRPC debug
99+
environment variables:
100+
101+
```sh
102+
export GRPC_VERBOSITY=debug
103+
export GRPC_TRACE=http,call_error,connectivity_state
104+
opentelemetry-instrument python YOUR_APP.py
105+
```

0 commit comments

Comments
 (0)