You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/manual-instrumentation.md
+10-76Lines changed: 10 additions & 76 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,97 +7,24 @@ The user is able to manually instrument their Python application
7
7
8
8
This guide shows you how to use the Elastic Distribution of OpenTelemetry Python (EDOT Python) to manually instrument your Python application and send OpenTelemetry data to an Elastic Observability deployment.
9
9
10
-
**Already familiar with OpenTelemetry?** It's an explicit goal of this distribution to introduce _no new concepts_ outside those defined by the wider OpenTelemetry community.
10
+
This guide requires to have already added autoinstrumentation with OpenTelemetry to your application per [Get started](./get-started.md).
11
11
12
12
**New to OpenTelemetry?** If your are new to OpenTelemetry we encourage you to take a look at our [get started documentation](./get-started.md) instead, which will introduce you to autoinstrumentation.
13
13
14
-
**Already added autoinstrumentation with OpenTelemetry to your application?** Skip to the [Manually instrument your Python application chapter](#Manually-instrument-your-Python-application).
15
-
16
-
<!-- ✅ What the user needs to know and/or do before they install EDOT Python -->
17
-
## Prerequisites
18
-
19
-
Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. EDOT Python supports sending data to any OpenTelemetry protocol (OTLP) endpoint, but this guide assumes you are sending data to an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one.
20
-
21
-
<details>
22
-
<summary><strong>Expand for setup instructions</strong></summary>
23
-
24
-
To create your first Elastic Observability deployment:
25
-
26
-
1. Sign up for a [free Elastic Cloud trial](https://cloud.elastic.co/registration) or sign into an existing account.
27
-
1. Go to <https://cloud.elastic.co/home>.
28
-
1. Click **Create deployment**.
29
-
1. When the deployment is ready, click **Open** to visit your Kibana home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`).
30
-
</details>
31
-
32
-
<!-- ✅ How to install EDOT Python -->
33
-
## Install
34
-
35
-
### Install the distribution
36
-
37
-
Install EDOT Python:
38
-
39
-
```bash
40
-
pip install elastic-opentelemetry
41
-
```
42
-
43
-
### Install the available instrumentation
44
-
45
-
EDOT Python does not install any instrumentation package by default, instead it relies on the
46
-
`opentelemetry-bootstrap` command to scan the installed packages and install the available instrumentation.
47
-
The following command will install all the instrumentations available for libraries found installed
48
-
in your environment:
49
-
50
-
```bash
51
-
opentelemetry-bootstrap --action=install
52
-
```
53
-
54
-
> [!NOTE]
55
-
> Add this command every time you deploy an updated version of your application (in other words, add it to your container image build process).
56
-
57
-
<!-- ✅ Start-to-finish operation -->
58
-
## Send data to Elastic
59
-
60
-
After installing EDOT Python, configure and initialize it to start sending data to Elastic.
61
-
62
14
<!-- ✅ Provide _minimal_ configuration/setup -->
63
15
### Configure EDOT Python
64
16
65
17
To configure EDOT Python, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and
66
18
authorization data to set a few `OTLP_*` environment variables that will be available when running EDOT Python:
67
19
68
-
*`OTEL_RESOURCE_ATTRIBUTES`: Use this to add a service name that will make it easier to recognize your application when reviewing data sent to Elastic.
69
-
*`OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent.
70
-
*`OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of `key=value` pairs that will
71
-
be added to the headers of every request. This is typically used for authentication information.
72
-
73
-
You can find the values of the endpoint and header variables in Kibana's APM tutorial. In Kibana:
74
-
75
-
1. Go to **Setup guides**.
76
-
1. Select **Observability**.
77
-
1. Select **Monitor my application performance**.
78
-
1. Scroll down and select the **OpenTelemetry** option.
79
-
1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there.
opentelemetry-instrument <command to start your service>
87
25
```
88
26
89
-
> [!NOTE]
90
-
> Alternatively, you can use an [APM agent key](https://www.elastic.co/guide/en/observability/current/apm-api-key.html) to authorize requests to an Elastic Observability endpoint. APM agent keys are revocable, you can have more than one of them, and you can add or remove them without restarting APM Server.
91
-
>
92
-
> To create and manage APM Agent keys in Kibana:
93
-
>
94
-
> 1. Go to **APM Settings**.
95
-
> 1. Select the **Agent Keys** tab.
96
-
>
97
-
> When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using different auth schema (`ApiKey` rather than `Bearer`). For example:
0 commit comments