Skip to content

Commit 4371e11

Browse files
committed
Consider manual instrumentation as next step for get-started
To drop most of duplicated content. Add cross reference between the two documents.
1 parent e29b6d3 commit 4371e11

File tree

2 files changed

+11
-76
lines changed

2 files changed

+11
-76
lines changed

docs/get-started.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,4 +129,5 @@ To confirm that EDOT Python has successfully connected to Elastic:
129129
## Next steps
130130

131131
* Reference all available [configuration options](./configure.md).
132+
* Learn how to add [manual instrumentation](./manual-instrumentation.md).
132133
* Learn more about viewing and interpreting data in the [Observability guide](https://www.elastic.co/guide/en/observability/current/apm.html).

docs/manual-instrumentation.md

Lines changed: 10 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -7,97 +7,24 @@ The user is able to manually instrument their Python application
77

88
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.
99

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).
1111

1212
**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.
1313

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-
6214
<!-- ✅ Provide _minimal_ configuration/setup -->
6315
### Configure EDOT Python
6416

6517
To configure EDOT Python, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and
6618
authorization data to set a few `OTLP_*` environment variables that will be available when running EDOT Python:
6719

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.
80-
81-
Here's an example:
82-
8320
```sh
8421
export OTEL_RESOURCE_ATTRIBUTES=service.name=<app-name>
8522
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
8623
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l"
24+
opentelemetry-instrument <command to start your service>
8725
```
8826

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:
98-
> ```sh
99-
> export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ=="
100-
> ```
27+
Refer to our [get started](./get-started.md) page for more details.
10128

10229
<!-- ✅ Manually instrument the application and start sending data to Elastic -->
10330
### Manually instrument your auto instrumented Python application
@@ -129,6 +56,13 @@ def hello():
12956
return f"Hello {choice}!"
13057
```
13158

59+
We need to make sure to have Flask and the Flask OpenTelemetry instrumentation installed:
60+
61+
```bash
62+
pip install flask
63+
opentelemetry-bootstrap --action=install
64+
```
65+
13266
And then we can run this application with the following command:
13367

13468
```bash

0 commit comments

Comments
 (0)