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/_edot-sdks/java/faq.md
+82-1
Original file line number
Diff line number
Diff line change
@@ -7,4 +7,85 @@ parent: EDOT Java
7
7
8
8
# Frequently Asked Questions on EDOT Java
9
9
10
-
TODO
10
+
## Does agent requires access to or modification of application code ?
11
+
12
+
No, the agent modifies the Java application binaries in bytecode form and does not requires original code nor
13
+
recompiling or re-packaging the application.
14
+
15
+
## How to disable the agent ?
16
+
17
+
There are two ways to disable the instrumentation agent:
18
+
19
+
- remove `-javaagent:` JVM argument
20
+
- set `OTEL_JAVAAGENT_ENABLED` environment variable or `otel.javaagent.enabled` Java system property to `false`
21
+
22
+
In both cases you need to restart the JVM.
23
+
24
+
## How to partially enable or disable the agent ?
25
+
26
+
It is possible to partially disable the agent, or to only selectively enable a limited set of instrumentations
27
+
by following instructions in the [upstream documentation](https://opentelemetry.io/docs/zero-code/java/agent/disable/).
28
+
29
+
## How to know if EDOT is attached to a running JVM ?
30
+
31
+
There are a few ways we can detect if the agent has been attached to a JVM
32
+
- in JVM logs, agent startup log message (see [below](#how-to-identify-the-version-of-edot-agent-)) might be included
33
+
- in JVM arguments `ps -ef|grep javaagent`
34
+
- in environment variables, for example `JAVA_TOOL_OPTIONS`, for example by inspecting the output of `export|grep javaagent`
35
+
36
+
## How to identify the version of EDOT agent ?
37
+
38
+
When the agent starts, a log message in the standard error provides the agent version:
39
+
```
40
+
INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.2.3
41
+
```
42
+
43
+
In addition, the `-javaagent:` JVM argument can provide the path to the agent file name, which _might_ also contain
44
+
the agent version, for example `-javaagent:elastic-otel-javaagent-1.2.3.jar`
45
+
46
+
When the original agent jar file has been renamed, it is still possible to inspect the `Implementation-Version` entry in `META-INF/MANIFEST.MF` file of the agent jar,
47
+
for example with `unzip -p elastic-otel-javaagent.jar META-INF/MANIFEST.MF|grep 'Implementation-Version'`
48
+
49
+
## What are the versions of the OpenTelemetry upstream dependencies ?
50
+
51
+
Because EDOT Java is a distribution of [OpenTelemetry Java instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation),
In order to review each of those individually, you can use the [EDOT release notes](https://github.com/elastic/elastic-otel-java/releases)
78
+
for links to the respective versions of each component.
79
+
80
+
### OpenTelemetry API/SDK update
81
+
82
+
In order to implement manual instrumentation, some applications use the OpenTelemetry API and/or SDK which allows them
83
+
to capture custom spans, metrics or even send data without any instrumentation agent.
84
+
85
+
Updates of the OpenTelemetry API/SDK in the application and the EDOT Java agent can be done independently.
86
+
- EDOT Java is backward-compatible with all previous versions of OpenTelemetry API/SDK
87
+
- Using a more recent version of API/SDK than the one in EDOT should usually work without problem, however to ensure maximum compatibility keeping OpenTelemetry API/SDK version ≤ EDOT OpenTelemetry API/SDK version is recommended.
88
+
89
+
### How to update
90
+
91
+
Updating EDOT Java agent is done by replacing the agent binary `.jar` that has been [added during setup](./setup/).
Copy file name to clipboardexpand all lines: docs/_edot-sdks/java/troubleshooting.md
+5-16
Original file line number
Diff line number
Diff line change
@@ -9,37 +9,26 @@ parent: EDOT Java
9
9
10
10
The sections below are in the order you should follow, unless you have already identified the section you need.
11
11
12
-
This guide assumes you have tested the other components in the route from application+agent to Elastic Observability (eg collector or APM server, Elasticsearch, and Kibana) and that the problem has been isolated to the application+agent.
12
+
This guide assumes you have tested the other components in the route from application+agent to Elastic Observability (eg collector, Elasticsearch, and Kibana) and that the problem has been isolated to the application+agent.
13
13
14
14
## General
15
15
16
16
Ensure you have set a service name (eg `-Dotel.service.name=Service1` or environment variable `OTEL_SERVICE_NAME` set to `Service1`) otherwise by default the data (traces, metrics, logs) will be sent to `unknown_service_java` - you may be getting data but it may all be under that service
17
17
18
18
## Connectivity to endpoint
19
19
20
-
Check _from_ the host/VM/pod/container/image running the app, that connectivity is available to the APM server or collector. The examples here use a default URL, which you should replace with the endpoint you are using:
20
+
Check _from_ the host/VM/pod/container/image running the app, that connectivity is available to the collector.
21
+
22
+
The examples here use a default URL `http://127.0.0.1:4318/, which you should replace with the endpoint you are using:
21
23
22
24
- OpenTelemetry or EDOT collector without authentication: `curl -i http://127.0.0.1:4318/v1/traces -X POST -d '{}' -H content-type:application/json`
23
-
- APM server without authentication: `curl --verbose -X GET http://127.0.0.1:8200`
24
-
- APM server with secret token authentication: `curl -X POST http://127.0.0.1:8200/ -H "Authorization: Bearer <secret_token>"`
25
-
- APM server with API key authentication: `curl -X POST http://127.0.0.1:8200/ -H "Authorization: ApiKey <api_key>"`
25
+
- OpenTelemetry or EDOT collector with API key authentication: `curl -i http://127.0.0.1:4318/v1/traces -X POST -d '{}' -H content-type:application/json -H "Authorization:ApiKey <api_key>"`
Copy file name to clipboardexpand all lines: docs/_edot-sdks/python/configuration.md
+60-5
Original file line number
Diff line number
Diff line change
@@ -5,9 +5,64 @@ nav_order: 2
5
5
parent: EDOT Python
6
6
---
7
7
8
-
# Configuring the EDOT Python SDK
8
+
# Configuration
9
9
10
-
TODO:
11
-
- describe the EDOT Python specific config options
12
-
- describe crucial upstream options
13
-
- refer to / link to the remaining upstream config options
10
+
Configure the Elastic Distribution of OpenTelemetry Python (EDOT Python) to send data to Elastic.
11
+
12
+
<!-- ✅ How users set configuration options -->
13
+
## Configuration method
14
+
15
+
<!-- Is this the right link to OpenTelemetry docs? -->
16
+
Configuration of the OpenTelemetry SDK should be performed through the mechanisms [documented on the OpenTelemetry website](https://opentelemetry.io/docs/zero-code/python/configuration/). EDOT Python is typically configured with `OTEL_*` environment variables defined by the OpenTelemetry spec. For example:
*[Specific configuration options that are _only_ available in EDOT Python](#configuration-options-that-are-only-available-in-edot-python)
32
+
33
+
### OpenTelemetry configuration options
34
+
35
+
EDOT Python supports all configuration options listed in the [OpenTelemetry General SDK Configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/general/) and [OpenTelemetry Python](https://opentelemetry.io/docs/languages/python).
36
+
37
+
#### Logs
38
+
39
+
Instrument Python `logging` module to format and forward logs in OTLP format is disabled by default and gated under a configuration environment variable:
> Enabling this will make any call to [logging.basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig) from your application a no-op.
47
+
48
+
#### Differences from OpenTelemetry Python
49
+
50
+
EDOT Python uses different defaults than OpenTelemetry Python for the following configuration options:
> `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` cloud resource detectors are dynamically set. When running in a Kubernetes Pod it will be set to `process_runtime,os,otel,telemetry_distro,service_instance,_gcp,aws_eks`.
60
+
61
+
62
+
### Configuration options that are _only_ available in EDOT Python
63
+
64
+
`ELASTIC_OTEL_` options are specific to Elastic and will always live in EDOT Python (they will _not_ be added upstream):
65
+
66
+
| Option(s) | Default | Description |
67
+
|---|---|---|
68
+
|`ELASTIC_OTEL_SYSTEM_METRICS_ENABLED`|`false`| When sets to `true`, sends *system namespace* metrics. |
Copy file name to clipboardexpand all lines: docs/_edot-sdks/python/index.md
+27-2
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,31 @@ layout: default
4
4
nav_order: 6
5
5
---
6
6
7
-
##EDOT Python
7
+
# EDOT Python
8
8
9
-
TODO: Put some content here
9
+
The [Elastic Distribution of OpenTelemetry Python (EDOT Python)](https://github.com/elastic/elastic-otel-python) is a customized version of [OpenTelemetry Python](https://opentelemetry.io/docs/languages/python).
10
+
EDOT Python makes it easier to get started using OpenTelemetry in your Python applications through strictly OpenTelemetry native means, while also providing a smooth and rich out of the box experience with [Elastic Observability](https://www.elastic.co/observability). It's an explicit goal of this distribution **to avoid introducing proprietary concepts** in addition to those defined by the wider OpenTelemetry community. For any additional features introduced we aim for contributing them back to the upstream OpenTelemetry Python project.
11
+
12
+
With EDOT Python you have access to all the features of the OpenTelemetry Python agent plus:
13
+
14
+
* Access to improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories.
15
+
* Access to optional features that can enhance OpenTelemetry data that is being sent to Elastic.
16
+
* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like an Elastic Observability deployment.
17
+
* Preconfigured collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default.
18
+
19
+
**Ready to try out EDOT Python?** Follow the step-by-step instructions in [Setup](./setup/index).
20
+
21
+
## Compatibility matrix
22
+
23
+
Data can be exported in the OpenTelemetry-native [OTLP (OpenTelemetry protocol)](https://opentelemetry.io/docs/specs/otlp) format via gRPC (default)
24
+
and HTTP to self-managed, Elastic Cloud Hosted or Elastic Cloud Serverless observability backends.
25
+
26
+
For the best (and supported) experience, we recommend exporting data from EDOT Python via the [EDOT Collector](https://elastic.github.io/opentelemetry/edot-collector/index).
Copy file name to clipboardexpand all lines: docs/_edot-sdks/python/migration.md
+134-6
Original file line number
Diff line number
Diff line change
@@ -5,10 +5,138 @@ nav_order: 5
5
5
parent: EDOT Python
6
6
---
7
7
8
-
# Migrating to EDOT Python from the Elastic Python Agent
8
+
# Migrating to EDOT Python from the Elastic APM Python Agent
9
9
10
-
TODO:
11
-
- migration steps
12
-
- advantages of using EDOT
13
-
- limitations compared to classic agents
14
-
- (optional) performance comparison
10
+
This guide will highlight the major differences between the [Elastic APM Python agent](https://www.elastic.co/guide/en/apm/agent/python/current/getting-started.html) and the Elastic Distribution of OpenTelemetry Python (EDOT Python).
11
+
For step-by-step instructions on setting up EDOT Python refer to the [Setup](./setup/index).
12
+
13
+
## We are a distribution
14
+
15
+
As a distribution of OpenTelemetry, EDOT Python follows certain standards, but there is still some space for innovation.
16
+
17
+
## EDOT Python principles
18
+
19
+
### Bold on auto-instrumentation
20
+
21
+
We have chosen to make auto-instrumentation as simple as possible so you can just focus on your code; we favored an experience that requires minimal changes to your application code. The upstream OpenTelemetry configuration has more options than the distribution requires. Our default configuration is listed [here](https://github.com/elastic/elastic-otel-python?tab=readme-ov-file#configuration).
22
+
23
+
### Bring your own instrumentation
24
+
25
+
In EDOT Python we decided to not ship all the available instrumentations in order to accommodate environments where installing more packages than requested may be an issue.
26
+
We provide a tool to discover available instrumentations automatically that can be added to your build workflow. See [Get started](https://github.com/elastic/elastic-otel-python/blob/main/docs/get-started.md#install-the-available-instrumentation).
27
+
28
+
## Performance overhead
29
+
30
+
Evaluate the [differences in performance overhead](./overhead) between EDOT Python and Elastic APM Python agent.
31
+
32
+
## Limitations
33
+
34
+
### Central and Dynamic configuration
35
+
36
+
Currently EDOT Python does not have an equivalent of the [central configuration feature](https://www.elastic.co/guide/en/observability/current/apm-agent-configuration.html) that the Elastic APM Python agent supports. When using EDOT Python, all the configurations are static and should be provided to the application with other configurations, e.g. environment variables.
37
+
38
+
### AWS lambda
39
+
40
+
At the moment, we are not building a custom lambda layer for our Python distribution. You can refer to the upstream [Lambda Auto-Instrumentation](https://opentelemetry.io/docs/faas/lambda-auto-instrument/).
41
+
42
+
### Missing instrumentations
43
+
44
+
Not all instrumentations we have in Elastic APM Python Agent have an OpenTelemetry counterpart. But we may port them if they are requested by users.
45
+
46
+
At the time of writing these docs, the following libraries are missing an OpenTelemetry instrumentation:
47
+
- aiobotocore
48
+
- aiomysql
49
+
- aiopg
50
+
- aioredis
51
+
- Azure storage and Azure queue
52
+
- Graphene
53
+
- httplib2
54
+
- pylibmc
55
+
- pyodbc
56
+
- Sanic
57
+
- zlib
58
+
59
+
### Integration with structured logging
60
+
61
+
EDOT Python does not have any [structlog integration](https://www.elastic.co/guide/en/apm/agent/python/current/logs.html#structlog) at the moment.
62
+
63
+
### Span compression
64
+
65
+
EDOT Python does not implement [span compression](https://www.elastic.co/guide/en/observability/current/apm-data-model-spans.html#apm-spans-span-compression).
66
+
67
+
### Breakdown metrics
68
+
69
+
EDOT Python is not sending metrics that power the [Breakdown metrics](https://www.elastic.co/guide/en/apm/guide/current/data-model-metrics.html#_breakdown_metrics).
70
+
71
+
## Migration steps
72
+
73
+
- remove any configuration and setup code needed by Elastic APM Python Agent from your application source code.
74
+
- migrate any eventual usage of Elastic APM Python Agent API for manual instrumentation with OpenTelemetry API in the application source code.
75
+
- follow [setup documentation](setup/index) on how to install and configure EDOT Python
76
+
77
+
## Option reference
78
+
79
+
This list contains Elastic APM Python agent configuration options that can be migrated to EDOT Python configuration because they have an equivalent in OpenTelemetry:
80
+
81
+
<!-- keep these sorted -->
82
+
*[api_key](#api_key)
83
+
*[enabled](#enabled)
84
+
*[environment](#environment)
85
+
*[global_labels](#global_labels)
86
+
*[metrics_interval](#metrics_interval)
87
+
*[secret_token](#secret_token)
88
+
*[server_url](#server_url)
89
+
*[service_name](#service_name)
90
+
*[service_version](#service_version)
91
+
92
+
### `api_key`
93
+
94
+
The Elastic [`api_key`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-api-key) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option.
95
+
96
+
For example:`OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_api_key"`.
97
+
98
+
### `enabled`
99
+
100
+
The Elastic [`enabled`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-enabled) option corresponds to the OpenTelemetry [OTEL_SDK_DISABLED](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) option.
101
+
102
+
### `environment`
103
+
104
+
The Elastic [`environment`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-environment) option corresponds to setting the `deployment.environment.name` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes).
105
+
106
+
For example: `OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=testing`.
107
+
108
+
### `global_labels`
109
+
110
+
The Elastic [`global_labels`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-global_labels) option corresponds to adding `key=value` comma separated pairs in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes).
111
+
112
+
For example: `OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second`. Such labels will result in labels.key=value attributes on the server, e.g. labels.alice=first
113
+
114
+
### `metrics_interval`
115
+
116
+
The Elastic [`metrics_interval`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-metrics_interval) corresponds to the OpenTelemetry [OTEL_METRIC_EXPORT_INTERVAL](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader) option.
117
+
118
+
For example: `OTEL_METRIC_EXPORT_INTERVAL=30000`.
119
+
120
+
### `secret_token`
121
+
122
+
The Elastic [`secret_token`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-secret-token) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option.
123
+
124
+
For example: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token"`.
125
+
126
+
### `server_url`
127
+
128
+
The Elastic [`server_url`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option.
129
+
130
+
### `service_name`
131
+
132
+
The Elastic [`service_name`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option.
133
+
134
+
The service name value can also be set using [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes).
135
+
136
+
For example: `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. If `OTEL_SERVICE_NAME` is set, it takes precedence over the resource attribute.
137
+
138
+
### `service_version`
139
+
140
+
The Elastic [`service_version`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-service-version) option corresponds to setting the `service.version` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes).
141
+
142
+
For example: `OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3`.
Every instrumentation agent comes with a (small) performance overhead for your application. How much really depends
11
+
on your application and on the instrumentations used.
12
+
13
+
While we can't provide generically applicable, accurate numbers about the performance overhead, here you can find some measurement taken
14
+
from a sample web application which allows to provide a comparison between agents and an order of magnitude of the effective overhead.
15
+
16
+
Those numbers are only provided as indicators, and you should not attempt to extrapolate them. You should however use
17
+
them as a framework to evaluate and measure the overhead on your applications.
18
+
19
+
The following table compares the response times of a sample web application without an agent, with Elastic APM Python Agent and with EDOT Python Agent in two situations: without data loaded and serialized to measure the minimal overhead of agents and with some data loaded and then serialized to provide a more common scenario.
Copy file name to clipboardexpand all lines: docs/_edot-sdks/python/setup/index.md
+69-4
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,72 @@ parent: EDOT Python
7
7
8
8
# Setting up EDOT Python
9
9
10
-
TODO:
11
-
- where to download
12
-
- explicit description of basic setup here (even if it overlaps with upstream docs)
13
-
- link to upstream docs for more advanced setup use cases
10
+
## Install
11
+
12
+
### Install the distribution
13
+
14
+
Install EDOT Python:
15
+
16
+
```bash
17
+
pip install elastic-opentelemetry
18
+
```
19
+
20
+
### Install the available instrumentation
21
+
22
+
EDOT Python does not install any instrumentation package by default, instead it relies on the
23
+
`edot-bootstrap` command to scan the installed packages and install the available instrumentation.
24
+
The following command will install all the instrumentations available for libraries found installed
25
+
in your environment:
26
+
27
+
```bash
28
+
edot-bootstrap --action=install
29
+
```
30
+
31
+
> [!NOTE]
32
+
> Add this command every time you deploy an updated version of your application (in other words, add it to your container image build process).
33
+
34
+
<!-- ✅ Start-to-finish operation -->
35
+
## Send data to Elastic
36
+
37
+
After installing EDOT Python, configure and initialize it to start sending data to Elastic.
38
+
39
+
<!-- ✅ Provide _minimal_ configuration/setup -->
40
+
### Configure EDOT Python
41
+
42
+
Refer to [Observability quickstart](https://elastic.github.io/opentelemetry/quickstart/) documentation on how to setup your environment.
43
+
44
+
To configure EDOT Python you need to set a few `OTLP_*` environment variables that will be available when running EDOT Python:
45
+
46
+
*`OTEL_RESOURCE_ATTRIBUTES`: Use this to add a `service.name` and `deployment.environment` that will make it easier to recognize your application when reviewing data sent to Elastic.
47
+
48
+
The following environment variables are not required if you are sending data through a local EDOT Collector but will be provided in the Elastic Observability platform onboarding:
49
+
50
+
*`OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent.
51
+
*`OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of `key=value` pairs that will be added to the headers of every request. This is typically used for authentication information.
52
+
53
+
54
+
### Run EDOT Python
55
+
56
+
Then wrap your service invocation with `opentelemetry-instrument`, which is the wrapper that provides _automatic instrumentation_:
57
+
58
+
```bash
59
+
opentelemetry-instrument <command to start your service>
60
+
```
61
+
62
+
For example, a web service running with gunicorn may look like this:
63
+
64
+
```bash
65
+
opentelemetry-instrument gunicorn main:app
66
+
```
67
+
68
+
<!-- ✅ What success looks like -->
69
+
## Confirm that EDOT Python is working
70
+
71
+
To confirm that EDOT Python has successfully connected to Elastic:
72
+
73
+
1. Go to **Observability** → **Applications** → **Service Inventory**
74
+
1. You should see the name of the service to which you just added EDOT Python. It can take several minutes after initializing EDOT Python for the service to show up in this list.
75
+
1. Click on the name in the list to see trace data.
76
+
77
+
> [!NOTE]
78
+
> There may be no trace data to visualize unless you have _invoked_ your application since initializing EDOT Python.
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.
12
+
13
+
This guide requires to have already added auto-instrumentation with OpenTelemetry to your application per [Setup](./index).
14
+
15
+
**New to OpenTelemetry?** If your are new to OpenTelemetry we encourage you to take a look at our [Setup documentation](./index) instead, which will introduce you to auto-instrumentation.
16
+
17
+
<!-- ✅ Provide _minimal_ configuration/setup -->
18
+
### Configure EDOT Python
19
+
20
+
Refer to our [Setup](./index#configure-edot-python) page for more details.
21
+
22
+
<!-- ✅ Manually instrument the application and start sending data to Elastic -->
23
+
### Manually instrument your auto instrumented Python application
24
+
25
+
In this section we'll show how to add manual instrumentation to an already automatically instrumented application. A use case for
26
+
this setup would be to trace something in particular while keeping the benefits of the simplicity of the automatic instrumentation doing
27
+
the hard work for us.
28
+
29
+
As an example we'll use an application using the Flask framework that implements an endpoint mounted on `/hello` returning a friendly
30
+
salute. This application is saved in a file named `app.py` that is the default module for Flask applications.
31
+
32
+
```
33
+
import random
34
+
35
+
from flask import Flask
36
+
from opentelemetry import trace
37
+
38
+
tracer = trace.get_tracer(__name__)
39
+
40
+
app = Flask(__name__)
41
+
42
+
@app.route("/hello")
43
+
def hello():
44
+
choices = ["there", "world", "folks", "hello"]
45
+
# create a span for the choice of the name, this may be a costly call in your real world application
46
+
with tracer.start_as_current_span("choice") as span:
47
+
choice = random.choice(choices)
48
+
span.set_attribute("choice.value", choice)
49
+
return f"Hello {choice}!"
50
+
```
51
+
52
+
53
+
We need to make sure to have Flask and the Flask OpenTelemetry instrumentation installed:
54
+
55
+
```bash
56
+
pip install flask
57
+
edot-bootstrap --action=install
58
+
```
59
+
60
+
And then we can run this application with the following command:
61
+
62
+
```bash
63
+
opentelemetry-instrument flask run
64
+
```
65
+
66
+
We may not only need to add a custom span to our application but also want to use a custom metric, like in the example below where we
67
+
are tracking how many times we are getting one of the possible choices for our salutes.
68
+
69
+
```
70
+
import random
71
+
72
+
from flask import Flask
73
+
from opentelemetry import metrics, trace
74
+
75
+
tracer = trace.get_tracer(__name__)
76
+
meter = metrics.get_meter(__name__)
77
+
78
+
hello_counter = meter.create_counter(
79
+
"hello.choice",
80
+
description="The number of times a salute is chosen",
81
+
)
82
+
83
+
app = Flask(__name__)
84
+
85
+
@app.route("/hello")
86
+
def hello():
87
+
choices = ["there", "world", "folks", "hello"]
88
+
# create a span for the choice of the name, this may be a costly call in your real world application
89
+
with tracer.start_as_current_span("choice") as span:
90
+
choice = random.choice(choices)
91
+
span.set_attribute("choice.value", choice)
92
+
hello_counter.add(1, {"choice.value": choice})
93
+
return f"Hello {choice}!"
94
+
```
95
+
96
+
<!-- ✅ What success looks like -->
97
+
## Confirm that EDOT Python is working
98
+
99
+
To confirm that EDOT Python has successfully connected to Elastic:
100
+
101
+
1. Go to **Observability** → **Applications** → **Service Inventory**
102
+
1. You should see the name of the service to which you just added EDOT Python. It can take several minutes after initializing EDOT Python for the service to show up in this list.
103
+
1. Click on the name in the list to see trace data.
104
+
105
+
> [!NOTE]
106
+
> There may be no trace data to visualize unless you have _used_ your application since initializing EDOT Python.
Copy file name to clipboardexpand all lines: docs/_edot-sdks/python/supported-technologies.md
+82-3
Original file line number
Diff line number
Diff line change
@@ -7,6 +7,85 @@ parent: EDOT Python
7
7
8
8
# Technologies Supported by the EDOT Python SDK
9
9
10
-
TODO:
11
-
- Reference the upstream Python instrumentation.
12
-
- Describe differences (also in default behavior) of EDOT Python compared to upstream.
10
+
## Python versions
11
+
12
+
The following Python versions are supported:
13
+
14
+
* 3.8
15
+
* 3.9
16
+
* 3.10
17
+
* 3.11
18
+
* 3.12
19
+
* 3.13
20
+
21
+
This follows the [OpenTelemetry Python Version Support](https://github.com/open-telemetry/opentelemetry-python/?tab=readme-ov-file#python-version-support).
22
+
23
+
## Instrumentations
24
+
25
+
We don't install instrumentations by default and we suggest to use our [edot-bootstrap](./setup/index#install-the-available-instrumentation) command to automatically install the available instrumentations.
26
+
27
+
| Name | Packages instrumented | Semantic conventions status |
28
+
|---|---|---|---|
29
+
| [elastic-opentelemetry-instrumentation-openai](https://github.com/elastic/elastic-otel-python-instrumentations/blob/main/instrumentation/elastic-opentelemetry-instrumentation-openai) | openai >= 1.2.0 | development
30
+
| [opentelemetry-instrumentation-aio-pika](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-aio-pika) | aio_pika >= 7.2.0, < 10.0.0 | development
| [opentelemetry-instrumentation-asyncio](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-asyncio) | asyncio | development
37
+
| [opentelemetry-instrumentation-asyncpg](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-asyncpg) | asyncpg >= 0.12.0 | development
38
+
| [opentelemetry-instrumentation-aws-lambda](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-aws-lambda) | | development
39
+
| [opentelemetry-instrumentation-boto](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-boto) | boto~=2.0 | development
40
+
| [opentelemetry-instrumentation-boto3sqs](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-boto3sqs) | boto3 ~= 1.0 | development
41
+
| [opentelemetry-instrumentation-botocore](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-botocore) | botocore ~= 1.0 | development
42
+
| [opentelemetry-instrumentation-cassandra](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-cassandra) | cassandra-driver ~= 3.25,scylla-driver ~= 3.25 | development
43
+
| [opentelemetry-instrumentation-celery](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-celery) | celery >= 4.0, < 6.0 | development
44
+
| [opentelemetry-instrumentation-click](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-click) | click >= 8.1.3, < 9.0.0 | development
45
+
| [opentelemetry-instrumentation-confluent-kafka](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-confluent-kafka) | confluent-kafka >= 1.8.2, <= 2.7.0 | development
46
+
| [opentelemetry-instrumentation-dbapi](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-dbapi) | dbapi | development
47
+
| [opentelemetry-instrumentation-django](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-django) | django >= 1.10 | development
48
+
| [opentelemetry-instrumentation-elasticsearch](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-elasticsearch) | elasticsearch >= 6.0 | development
| [opentelemetry-instrumentation-logging](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-logging) | logging | development
57
+
| [opentelemetry-instrumentation-mysql](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-mysql) | mysql-connector-python >= 8.0, < 10.0 | development
58
+
| [opentelemetry-instrumentation-mysqlclient](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-mysqlclient) | mysqlclient < 3 | development
59
+
| [opentelemetry-instrumentation-pika](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pika) | pika >= 0.12.0 | development
60
+
| [opentelemetry-instrumentation-psycopg](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-psycopg) | psycopg >= 3.1.0 | development
61
+
| [opentelemetry-instrumentation-psycopg2](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-psycopg2) | psycopg2 >= 2.7.3.1,psycopg2-binary >= 2.7.3.1 | development
62
+
| [opentelemetry-instrumentation-pymemcache](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymemcache) | pymemcache >= 1.3.5, < 5 | development
63
+
| [opentelemetry-instrumentation-pymongo](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymongo) | pymongo >= 3.1, < 5.0 | development
64
+
| [opentelemetry-instrumentation-pymssql](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymssql) | pymssql >= 2.1.5, < 3 | development
65
+
| [opentelemetry-instrumentation-pymysql](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymysql) | PyMySQL < 2 | development
66
+
| [opentelemetry-instrumentation-pyramid](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pyramid) | pyramid >= 1.7 | development
67
+
| [opentelemetry-instrumentation-redis](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-redis) | redis >= 2.6 | development
68
+
| [opentelemetry-instrumentation-remoulade](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-remoulade) | remoulade >= 0.50 | development
Copy file name to clipboardexpand all lines: docs/_edot-sdks/python/troubleshooting.md
+49-1
Original file line number
Diff line number
Diff line change
@@ -7,4 +7,52 @@ parent: EDOT Python
7
7
8
8
# Troubleshooting the EDOT Python Agent
9
9
10
-
TODO
10
+
Below are some resources and tips for troubleshooting and debugging the Elastic Distribution of OpenTelemetry Python (EDOT Python).
11
+
12
+
-[Easy Fixes](#easy-fixes)
13
+
-[Disable EDOT](#easy-fixes)
14
+
15
+
## Easy Fixes
16
+
17
+
Before you try anything else, go through the following sections to ensure that
18
+
EDOT Python is configured correctly. This is not an exhaustive list, but rather
19
+
a list of common problems that users run into.
20
+
21
+
### Debug and development modes
22
+
23
+
Most frameworks support a debug mode. Generally, this mode is intended for
24
+
non-production environments and provides detailed error messages and logging of
25
+
potentially sensitive data. So enabling instrumentation in debug mode is not advised and may pose privacy and security issues in recording
26
+
sensitive data.
27
+
28
+
#### Django
29
+
30
+
Django applications running with the Django `runserver` need to use the `--noreload` parameter in order to be instrumented with `opentelemetry-instrument`.
31
+
Remember that you also need to set the `DJANGO_SETTINGS_MODULE` environment variable pointing to the application settings module.
32
+
33
+
#### FastAPI
34
+
35
+
FastAPI application started with `fastapi dev` requires the reloader to be disabled with `--no-reload` in order to be instrumented with `opentelemetry-instrument`.
36
+
37
+
#### Flask
38
+
39
+
Flask applications running in debug mode will require to disable the reloader in order to being traced, see [OpenTelemetry zero code documentation](https://opentelemetry.io/docs/zero-code/python/example/#instrumentation-while-debugging).
40
+
41
+
## Disable EDOT
42
+
43
+
In the unlikely event EDOT Python causes disruptions to a production application, you can disable it while you troubleshoot.
44
+
45
+
To disable the underlying OpenTelemetry SDK you set the following environment variable `OTEL_SDK_DISABLED=true`.
46
+
47
+
If only a subset of instrumentation are causing disruptions you can disable them with the `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS`
48
+
environment variable. It accepts a list of comma separated instrumentations to disable, see [OpenTelemetry zero code documentation](https://opentelemetry.io/docs/zero-code/python/configuration/#disabling-specific-instrumentations)
49
+
50
+
## Missing logs
51
+
52
+
Enabling the Python logging module auto-instrumentation with `OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true` calls the
53
+
[logging.basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig) method that will make your own application calls
54
+
to it a no-op. The side effect of this is that you won't see your application logs in the console anymore.
55
+
56
+
If you are already shipping logs by other means you don't need to enable this.
57
+
58
+
<!-- TODO: when available add link to to propose other option https://elastic.github.io/opentelemetry/use-cases/logs/ -->
Other, non-EDOT distributions of the OTel Collector (such as custom Collector builds, upstream Collector distributions, etc.) are *not* officially supported through Elastic but deemed **technically compatible** (🟡) if they contain the [required OTel Collector components](../edot-collector/custom-collector) and are configured analogously to the EDOT Collector.
104
+
105
+
Required components and configuration options per use case can be retrieved from the [sample configuration files](https://github.com/elastic/elastic-agent/tree/v{{ site.edot_versions.collector }}/internal/pkg/otel/samples/linux) for the EDOT Collector.
OpenTelemetry (OTel) is a modular, extensible framework designed to integrate with a wide range of technologies. Its architecture enables interoperability across many components, extensions, and tools—giving users flexibility to shape their observability pipelines.
11
+
12
+
Elastic Distributions for OpenTelemetry (EDOT) are built from upstream OTel components and are **technically compatible** with a broad set of community components. Users can also send data to Elastic using other upstream OTel components or distributions like the contrib Collector and OTel SDKs, which are *technically compatible* with Elastic’s ingestion APIs.
13
+
14
+
**"Supported through Elastic”** refers to components and configurations that Elastic has explicitly tested, validated, and committed to maintaining under our [Support Policies](https://www.elastic.co/support). This includes regular updates, issue triaging, and guidance from Elastic’s support and engineering teams. Components outside of this supported set may still work, but Elastic does not provide guaranteed support or troubleshooting assistance for them.
15
+
16
+
In the following sections we differentiate the following compatibility and support states:
17
+
18
+
| State | Description | Symbol |
19
+
|:---|:---|:---:|
20
+
|**Incompatible**| Component, use case or ingestion path is technically not compatible, thus, functionality is likely to be significantly impacted. | ❌ |
21
+
|**Compatible**| Component, use case or ingestion path is **technically compatible**. The functionality is not expected to be impaired, though, minor deviations may occur. Component, use case or ingestion path is *not officially support by Elastic*, hence, Elastic does not provide guaranteed support or troubleshooting assistance | 🟡 |
22
+
|**Supported**| Component, use case or ingestion path is **technically compatible** and Elastic provides **official support**. The functionality is explicitly tested. Limitations will be documented. | ✅ |
23
+
24
+
## EDOT Collector Components Categorization
25
+
The EDOT Collector includes two types of components with different compatibility and support scope:
26
+
27
+
### Core Components
28
+
29
+
These are used by default in Elastic’s onboarding flows and are essential for common use cases.
30
+
They are **fully supported** (✅) under your Service Level Agreement (SLA).
31
+
32
+
### Extended Components
33
+
34
+
A curated set of optional components that enhance functionality and are **technically compatible** (🟡).
35
+
These are not part of Elastic’s core product journeys and are not covered by SLAs.
36
+
You’re free to use them, but Elastic provides limited support.
37
+
38
+
{: .note-title}
39
+
> Recommendation
40
+
>
41
+
> For the best support experience, we recommend relying on *Core Components*, and using *Extended Components* only when required.
42
+
43
+
{: .warning}
44
+
> Since the EDOT Collector is built on upstream OpenTelemetry, breaking upstream changes (e.g., to semantic conventions or configuration options) may impact both, *Extended Components* and *Core Components*. Elastic highlights and manages these through docs and support channels.
Applications make more and more use of Generative Artificial Intelligence (GenAI). Telemetry data in terms of spans, metrics and logs when communicating with the GenAI APIs becomes more and more important to operate the application in production and understand the application's behavior and health state.
10
+
11
+
We currently support LLM observability with our EDOT Java, EDOT Node.js and EDOT Python as tech preview. In the following, the supported technologies are listed as well as quickstart instructions to instrument your application to get telemetry data.
See the [Supported Technologies section in the corresponding EDOT SDK](../../edot-sdks/index) for detailed information on supported versions.
21
+
22
+
# Quickstart
23
+
24
+
This quick start describes the setup and collection of OpenTelemetry data for LLM applications.
25
+
26
+
1.**Setup**
27
+
28
+
Choose the environment and target system from the [quick start overview](../../quickstart/index) and follow the setup instructions to instrument your LLM application. The instrumentation for the supported technologies is enabled by default.
29
+
30
+
2.**Configuration**
31
+
32
+
See the [Configuration section in the corresponding EDOT SDK](../../edot-sdks/index) to enable and disable specific instrumentations and to see what instrumentation is enabled by default.
33
+
34
+
When you finish the setup and the configuration of the EDOT SDK and there is a workload on your application, you should start to see telemetry data in Kibana. If there is no telemetry data showing up, please see the troubleshooting of the EDOT SDK,
0 commit comments