Skip to content

Commit ce282f1

Browse files
NathanielRNNathanielRN
authored
Update OTel Python Getting Started SDK (#167)
1 parent d9d5c92 commit ce282f1

File tree

3 files changed

+277
-133
lines changed

3 files changed

+277
-133
lines changed

‎src/docs/getting-started/python-sdk.mdx

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,19 +8,18 @@ path: '/docs/getting-started/python-sdk'
88

99
import SectionSeparator from "components/MdxSectionSeparator/sectionSeparator.jsx"
1010

11-
OpenTelemetry provides different language SDKs to instrument code for collecting telemetry data in the application.
11+
# Getting Started with the Python SDK on Traces and Metrics Instrumentation
1212

13-
In this tutorial, we will introduce how to use OpenTelemetry Python SDK for manual instrumentation on traces and metrics in the applications.
13+
The AWS Distro for OpenTelemetry (ADOT) Python refers to some components developed to complement the upstream [OpenTelemetry (OTel) Python SDK](https://github.com/open-telemetry/opentelemetry-python/tree/main/opentelemetry-sdk). Below are links to guides that go over how to configure the relevant components of the OpenTelemetry SDK to send trace data to the AWS X-Ray backend.
1414

1515
<SectionSeparator />
1616

17-
## Getting Started
18-
19-
* [Auto Instrumentation with the Python SDK](/docs/getting-started/python-sdk/trace-auto-instr)
20-
* [Manual Instrumentation with the Python SDK](/docs/getting-started/python-sdk/trace-manual-instr)
21-
22-
## Sample Code with Python SDK
23-
* [Sample applications on GitHub](https://github.com/aws-observability/aws-otel-python/tree/main/integration-test-apps)
17+
## Getting Started
2418

19+
* [Auto Instrumentation for Traces with the Python SDK](/docs/getting-started/python-sdk/trace-auto-instr)
20+
* [Manual Instrumentation for Traces with the Python SDK](/docs/getting-started/python-sdk/trace-manual-instr)
2521

22+
## Sample Code
2623

24+
* [Sample Flask App using OpenTelemetry Python SDK Automatic Instrumentation](https://github.com/aws-observability/aws-otel-python/tree/main/integration-test-apps/auto-instrumentation/flask)
25+
* [Sample Flask App using OpenTelemetry Python SDK Manual Instrumentation](https://github.com/aws-observability/aws-otel-python/tree/main/integration-test-apps/manual-instrumentation/flask)

‎src/docs/getting-started/python-sdk/trace-auto-instr.mdx

Lines changed: 59 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: 'ADOT Python - Auto Instrumentation Documentation'
2+
title: 'ADOT Python - Auto-Instrumentation Documentation'
33
description:
44
OpenTelemetry provides different language SDKs to instrument code for collecting telemetry data in the application.
55
In this tutorial, we will introduce how to use OpenTelemetry Python SDK for traces and metrics instrumentation in the application...
@@ -9,105 +9,105 @@ path: '/docs/getting-started/python-sdk/trace-auto-instr'
99
import SectionSeparator from "components/MdxSectionSeparator/sectionSeparator.jsx"
1010
import SubSectionSeparator from "components/MdxSubSectionSeparator/subsectionSeparator.jsx"
1111

12+
# Tracing with the AWS Distro for OpenTelemetry Python Auto-Instrumentation
1213

13-
The AWS Distro for OpenTelemetry Python (ADOT Python) provides functionality to [OpenTelemetry Python](https://github.com/open-telemetry/opentelemetry-python) for use with AWS X-Ray. OpenTelemetry Python supports automatic instrumentation, which instruments your application to gather telemetry data from a diverse set of libraries and frameworks with minimal configuration. This data can then be exported to different back-ends in different formats.
14+
## Introduction
1415

15-
In this tutorial, we will introduce automatic instrumentation using ADOT Python for AWS X-Ray.
16+
OpenTelemetry Python supports automatic instrumentation. It automatically produces spans with telemetry data describing the values used by the python frameworks in your application without adding a single line of code. This telemetry data can then be exported to a backend like AWS X-Ray using the ADOT Python `opentelemetry-sdk-extension-aws` package.
17+
18+
In this guide, we walk through the steps needed to trace an application with auto-instrumentation.
1619

1720
<SectionSeparator />
1821

1922
## Requirements
2023

21-
Python 3.6+ is required to use OpenTelemetry Python. Check your currently installed Python version using `python3 -V`.
22-
For more information about supported Python versions, see the [OpenTelemetry Python API package on PyPi](https://pypi.org/project/opentelemetry-api/).
24+
Python 3.6 or later is required to run an application using OpenTelemetry.
2325

24-
Make sure you have AWS Distro for OpenTelemetry Collector (ADOT Collector) running. To set up the collector, see
25-
[Getting Started with the AWS Distro for OpenTelemetry Collector](https://aws-otel.github.io/docs/getting-started/collector).
26+
Note: You’ll also need to have the [ADOT Collector](https://aws-otel.github.io/docs/getting-started/collector) running to export traces to X-Ray.
2627

2728
<SectionSeparator />
2829

29-
## Getting the SDKs and dependencies
30+
## Installation
3031

31-
The OpenTelemetry instrumentation package automates much of the on-boarding process. See the package usage later in this documentation.
32+
The easiest way to download the packages needed for auto-instrumentation is using pip:
3233

33-
### Install instrumentation packages
34+
```bash
35+
# Install required packages for instrumentation and to support tracing with AWS X-Ray
36+
$ pip install opentelemetry-distro[otlp]>=0.24b0 \
37+
opentelemetry-sdk-extension-aws~=1.0.0
38+
```
3439

35-
You will need to install the `opentelemetry-distro` package from PyPi. This automatically installs the `opentelemetry-api`, `opentelemetry-sdk`, and `opentelemetry-instrumentation` packages. `opentelemetry-instrumentation` provides commands to detect, install, and initialize all instrumentation packages supported for your application’s dependencies.
40+
Installing the `opentelemetry-sdk-extension-aws` package automatically installs the `opentelemetry-api`, `opentelemetry-sdk`, and `opentelemetry-instrumentation` packages as dependencies.
3641

37-
Also, you will want to install `opentelemetry-sdk-extension-aws` to make traces compatible with AWS X-Ray.
42+
`opentelemetry-instrumentation` provides commands to detect, install, and initialize all instrumentation packages supported for your application’s dependencies. Notably, it installs the `opentelemetry-bootstrap` and `opentelemetry-instrument` executables on your system.
3843

39-
Go to the directory of the application which you want to instrument and run the following commands.
44+
Go to the directory of the python application which you want to instrument. Here, use the `opentelemetry-bootstrap` command to automatically detect and install OpenTelemetry python packages. These packages contain `Instrumentors` that will instrument the packages your system has downloaded and that your application is already using.
4045

41-
```bash
42-
$ # Install required packages for instumentation and tracing support for AWS X-Ray
43-
$ pip install opentelemetry-distro[otlp]>=0.22b0 \
44-
opentelemetry-sdk-extension-aws>=0.22b0
45-
# Automatically install supported instrumentors for the application's dependencies
46+
```bash
47+
# Automatically install supported Instrumentors for the application's dependencies
4648
$ opentelemetry-bootstrap --action=install
47-
```
48-
49-
<SubSectionSeparator />
49+
```
5050

51-
### Setting the global propagators
51+
For example, if you have `boto3` installed, this command will automatically install the `opentelemetry-instrumentation-botocore` package which auto-instrumentation can subsequently configure automatically. Check out the OpenTelemetry registry for a [full list of instrumentation packages provided by OpenTelemetry Python](https://opentelemetry.io/registry/?s=&component=instrumentation&language=python).
5252

53-
To allow the span context to propagate downstream when the application makes calls to external services, configure the global propagator.
54-
Set the `OTEL_PROPAGATORS` environment variable to use the AWS X-Ray Propagator.
53+
<SubSectionSeparator />
5554

56-
```
57-
OTEL_PROPAGATORS=aws_xray
58-
```
55+
## Running an Application with Auto-Instrumentation
5956

60-
<SubSectionSeparator />
57+
Auto-instrumentation uses the `opentelemetry-instrument` executable functions as a wrapper to automatically initialize the `Instrumentors` installed by the `opentelemetry-bootstrap` command and start the provided application.
6158

62-
### Run the application
59+
The AWS X-Ray Id Generator can be configured using an environment variable as `OTEL_PYTHON_ID_GENERATOR=aws_xray`, and the AWS X-Ray Propagator can be configured using `OTEL_PROPAGATORS=xray`.
6360

64-
Auto instrumentation uses the `opentelemetry-instrument` wrapper executable to automatically initialize the installed instrumentors and start the provided application. Environment variables are used to configure the connection to the ADOT Collector and command line arguments are used to configure trace generation for AWS X-Ray.
61+
Currently, it is not possible to configure the Resource Detectors using auto-instrumentation.
6562

66-
The `IdGenerator` can be configured with the environment variables `OTEL_PYTHON_ID_GENERATOR=aws_xray` or the `opentelemetry-instrument` command line argument `--id-generator=aws_xray`.
63+
Putting this all together, starting your application using auto-instrumentation can be as simple as the following:
6764

68-
The `SpanExporter` can be configured with the environment variables `OTEL_TRACES_EXPORTER=otlp` or the `opentelemetry-instrument` command line argument `--trace-exporter=otlp`. However, if `opentelemetry-distro[otlp]` is used, it already uses the `otlp` exporter by default with any more configuration.
65+
```bash
66+
$ OTEL_PROPAGATORS=xray \
67+
OTEL_PYTHON_ID_GENERATOR=xray \
68+
opentelemetry-instrument python3 ./path/to/your/app.py
69+
```
6970

70-
The configuration of your SDK exporter depends on how you have configured your ADOT Collector. To learn more about how the ADOT Collector can be configured, refer to the [ADOT Collector Documentation](https://aws-otel.github.io/docs/getting-started/collector).
71+
### Configuring Auto-Instrumentation
7172

72-
We can use the `OTEL_EXPORTER_OTLP_ENDPOINT=localhost:55678` environment variable to set the address that the exporter will use to connect to the collector. If the address is unset, it will instead try to connect to `localhost:4317`.
73+
Environment variables are the primary way in which the OpenTelemetry SDK for Python is configured to enable compatibility with the AWS X-Ray backend. Some key environment variables are:
7374

74-
If the Collector the application will connect to is running without TLS configured, the `OTEL_EXPORTER_OTLP_INSECURE=True` environment variable is used to disable client transport security for an SDK OTLP exporter’s connection. This will use the gRPC insecure_channel() method as explained in the [gRPC Python Documentation](https://grpc.github.io/grpc/python/grpc.html?highlight=insecure#grpc.insecure_channel). This option should never be used in production, non-sidecar deployments.
75+
* `OTEL_PYTHON_ID_GENERATOR`
76+
* `OTEL_PROPAGATORS`
77+
* `OTEL_TRACES_EXPORTER`
78+
* `OTEL_EXPORTER_OTLP_ENDPOINT`
79+
* `OTEL_EXPORTER_OTLP_CERTIFICATE`
7580

76-
If the Collector the application will connect to is running with TLS configured, the `OTEL_EXPORTER_OTLP_CERTIFICATE=/path/to/my-cert.crt` environment variable is used to give a path to credentials to be used to establish a secure connection for the app’s exporter. The credentials at this path should be the public certificate of the collector, or one of its root certificates. If no certificate is found, the gRPC method `ssl_channel_credentials()` will attempt to “retrieve the PEM-encoded root certificates from a default location chosen by gRPC runtime” as explained in the [gRPC Python Documentation](https://grpc.github.io/grpc/python/grpc.html?highlight=ssl_channel_credentials).
81+
The `IdGenerator` can be configured to use the AWS X-Ray Id Generator with an environment variable as `OTEL_PYTHON_ID_GENERATOR=aws_xray` to ensure spans use an Id format compatible with the AWS X-Ray backend.
7782

78-
#### Examples on running the application
83+
The global propagator can be configured to use the AWS X-Ray Propagator with an environment variable as `OTEL_PROPAGATORS=xray` to allow the span context to propagate downstream when the application makes calls to external services.
7984

80-
Starting an application which connects to a Collector running as a sidecar without TLS:
85+
The `SpanExporter` can be configured with an environment variables `OTEL_TRACES_EXPORTER=otlp` to export spans in the format required by the ADOT Collector. However, if `opentelemetry-distro[otlp]` is used, it already uses the `otlp` exporter by default without the need for any more configuration.
8186

82-
```bash
83-
$ OTEL_EXPORTER_OTLP_INSECURE=True \
84-
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317 \
85-
OTEL_PROPAGATORS=aws_xray \
86-
OTEL_PYTHON_ID_GENERATOR=aws_xray \
87-
opentelemetry-instrument python ./path/to/your/app.py
88-
```
87+
The configuration of your SDK exporter depends on how you have configured your ADOT Collector. To learn more about how the ADOT Collector can be configured, refer to the [ADOT Collector Documentation](https://aws-otel.github.io/docs/getting-started/collector).
8988

90-
Starting an application which connects to a Collector running as a sidecar without TLS using flask:
89+
We can use the `OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317` environment variable to set the address that the exporter will use to connect to the collector. If unset, the SDK will try to connect to `http://localhost:4317` by default. Note that because the scheme is `http` by default, you have to explicitly set it to be `https` if necessary.
9190

92-
```bash
93-
$ OTEL_EXPORTER_OTLP_INSECURE=True \
94-
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317 \
95-
FLASK_APP=./my_flask_app.py \
96-
OTEL_PROPAGATORS=aws_xray \
97-
OTEL_PYTHON_ID_GENERATOR=aws_xray \
98-
opentelemetry-instrument flask run
99-
```
91+
If the Collector the application will connect to is running with TLS configured, the `OTEL_EXPORTER_OTLP_CERTIFICATE=/path/to/my-cert.crt` environment variable is used to give a path to credentials to be used to establish a secure connection for the app’s exporter. The credentials at this path should be the public certificate of the collector, or one of its root certificates. If no certificate is found, the gRPC method `ssl_channel_credentials()` will attempt to “retrieve the PEM-encoded root certificates from a default location chosen by gRPC runtime” as explained in the [gRPC Python Documentation](https://grpc.github.io/grpc/python/grpc.html?highlight=ssl_channel_credentials).
10092

101-
Starting an application which connects to a Collector running as a service with TLS:
93+
Thus, an advanced configuration of auto-instrumentation may look like this:
10294

10395
```bash
10496
$ OTEL_EXPORTER_OTLP_CERTIFICATE=/path/to/my-cert.crt \
10597
OTEL_EXPORTER_OTLP_ENDPOINT=collector.service.local \
106-
OTEL_PROPAGATORS=aws_xray \
107-
OTEL_PYTHON_ID_GENERATOR=aws_xray \
108-
opentelemetry-instrument python ./path/to/your/app.py
98+
OTEL_PROPAGATORS=xray \
99+
OTEL_PYTHON_ID_GENERATOR=xray \
100+
opentelemetry-instrument python3 ./path/to/your/app.py
109101
```
110102

111103
<SectionSeparator />
112104

113-
Custom tracing works the same way when using automatic instrumentation or manual instrumentation. For information about custom trace instrumentation, see our [docs on manual instrumentation](/docs/getting-started/python-sdk/trace-manual-instr).
105+
## Using Manual Instrumentation
106+
107+
Because there can only be one global `TracerProvider`, manual instrumentation should not instantiate its own `TracerProvider` if used together alongside auto-instrumentation. Given that the same `TracerProvider` is used, custom tracing works the same way when using automatic instrumentation or manual instrumentation. For information about custom trace instrumentation, see our [docs on manual instrumentation](/docs/getting-started/python-sdk/trace-manual-instr).
108+
109+
<SectionSeparator />
110+
111+
## Sample Application
112+
113+
See a [sample Flask App using OpenTelemetry Python SDK Automatic Instrumentation](https://github.com/aws-observability/aws-otel-python/tree/main/integration-test-apps/auto-instrumentation/flask)

0 commit comments

Comments
 (0)