diff --git a/README.md b/README.md index 6f282c48..a4effcdf 100644 --- a/README.md +++ b/README.md @@ -15,67 +15,13 @@ With EDOT Python you have access to all the features of the OpenTelemetry Python * Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like an Elastic Observability deployment. * Preconfigured collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. -**Ready to try out EDOT Python?** Follow the step-by-step instructions in [Get started](./docs/get-started.md). - -## Read the docs - -* [Get started](./docs/get-started.md) -* [Supported technologies](./docs/supported-techologies.md) -* [Manual instrumentation](./docs/manual-instrumentation.md) -* [Configuration](./docs/configure.md) -* [Migrating from Elastic APM Python Agent](./docs/migrate-from-apm.md) -* [Troubleshooting](./docs/troubleshooting.md) - -## Install - -```bash -pip install elastic-opentelemetry -``` - - - -## Usage - -Our distribution does not install any instrumentation package by default, instead it relies on the -`edot-bootstrap` command to scan the installed packages and install the available instrumentation, preferring EDOT variants when available. -The following command will install all the instrumentations available for libraries found installed -in your environment: - -```bash -edot-bootstrap --action=install -``` - -It will be useful to add this command every time you need to deploy an updated version of your application, -e.g. into your container image build process. - -At runtime you have to make some environment variables available to provide the needed configuration. -A *service name* is required to have your app easily recognizable from the other. Then you need to provide -the *authorization* headers for authentication with Elastic cloud and the project endpoint where to send your data. - -```bash -OTEL_RESOURCE_ATTRIBUTES=service.name= -OTEL_EXPORTER_OTLP_HEADERS="Authorization=" -OTEL_EXPORTER_OTLP_ENDPOINT= -``` - -We are done with the configuration and the last piece of the puzzle is wrapping your service invocation with -`opentelemetry-instrument` that is the wrapper that provides *automatic instrumentation*: - -```bash -opentelemetry-instrument -``` - -For a web service running with gunicorn it may looks like: - -```bash -opentelemetry-instrument gunicorn main:app -``` +**Ready to try out EDOT Python?** Follow the step-by-step instructions in [Setting up EDOT Python](https://elastic.github.io/opentelemetry/edot-sdks/python/setup/index.html). ## Configuration The distribution supports all the configuration variables from OpenTelemetry Python project version 1.31.1. -See [Configuration](./docs/configure.md) for more details. +See [Configuration](https://elastic.github.io/opentelemetry/edot-sdks/python/configuration.html) for more details. ## License diff --git a/docs/configure.md b/docs/configure.md deleted file mode 100644 index 9de20ab9..00000000 --- a/docs/configure.md +++ /dev/null @@ -1,68 +0,0 @@ - - -# Configuration - -Configure the Elastic Distribution of OpenTelemetry Python (EDOT Python) to send data to Elastic. - - -## Configuration method - - -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: - -```sh -export OTEL_RESOURCE_ATTRIBUTES=service.name= -export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io -export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" -opentelemetry-instrument -``` - - -## Configuration options - -Because the Elastic Distribution of OpenTelemetry Python is an extension of OpenTelemetry Python, it supports both: - -* [General OpenTelemetry configuration options](#opentelemetry-configuration-options) -* [Specific configuration options that are _only_ available in EDOT Python](#configuration-options-that-are-only-available-in-edot-python) - -### OpenTelemetry configuration options - -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). - -#### Logs - -Instrument Python `logging` module to format and forward logs in OTLP format is disabled by default and gated under a configuration environment variable: - -```sh -export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true -``` - -> [!NOTE] -> 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. - -#### Differences from OpenTelemetry Python - -EDOT Python uses different defaults than OpenTelemetry Python for the following configuration options: - -| Option | EDOT Python default | OpenTelemetry Python default | -|---|---|---| -| `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` | `process_runtime,os,otel,telemetry_distro,service_instance,_gcp,aws_ec2,aws_ecs,aws_elastic_beanstalk,azure_app_service,azure_vm` | `otel` | -| `OTEL_METRICS_EXEMPLAR_FILTER` | `always_off` | `trace_based` | -| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | `DELTA` | `CUMULATIVE` | - -> [!NOTE] -> `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`. - - -### Configuration options that are _only_ available in EDOT Python - -`ELASTIC_OTEL_` options are specific to Elastic and will always live in EDOT Python (they will _not_ be added upstream): - -| Option(s) | Default | Description | -|---|---|---| -| `ELASTIC_OTEL_SYSTEM_METRICS_ENABLED` | `false` | When sets to `true`, sends *system namespace* metrics. | diff --git a/docs/get-started.md b/docs/get-started.md deleted file mode 100644 index 786e5390..00000000 --- a/docs/get-started.md +++ /dev/null @@ -1,156 +0,0 @@ - - -# Get started - -This guide shows you how to use the Elastic Distribution of OpenTelemetry Python (EDOT Python) to instrument your Python application and send OpenTelemetry data to an Elastic Observability deployment. - -**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. - -**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get EDOT Python set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up EDOT Python initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/python/). - - -## Prerequisites - -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. - -
-Expand for Elastic Observability deployment setup instructions - -To create your first Elastic Observability deployment: - -1. Sign up for a [free Elastic Cloud trial](https://cloud.elastic.co/registration) or sign into an existing account. -1. Go to . -1. Click **Create deployment**. -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`). -
- -
-Expand for Elastic Observability Serverless setup instructions - -To create your first Elastic Observability Serverless project: - -1. Sign up for a [free Elastic Cloud trial](https://cloud.elastic.co/registration) or sign into an existing account. -1. Go to . -1. Click **Create project**. -1. When the project is ready, click **Open** to visit your Kibana home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`). -
- - -## Install - -### Install the distribution - -Install EDOT Python: - -```bash -pip install elastic-opentelemetry -``` - -### Install the available instrumentation - -EDOT Python does not install any instrumentation package by default, instead it relies on the -`edot-bootstrap` command to scan the installed packages and install the available instrumentation. -The following command will install all the instrumentations available for libraries found installed -in your environment: - -```bash -edot-bootstrap --action=install -``` - -> [!NOTE] -> Add this command every time you deploy an updated version of your application (in other words, add it to your container image build process). - - -## Send data to Elastic - -After installing EDOT Python, configure and initialize it to start sending data to Elastic. - - -### Configure EDOT Python - -To configure EDOT Python, at a minimum you'll need your Elastic Observability cloud OTLP endpoint and -authorization data to set a few `OTLP_*` environment variables that will be available when running EDOT Python: - -* `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. -* `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent. -* `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. - -You can find the values of the endpoint and header variables in Kibana's APM tutorial. In Kibana: - -1. Go to **Setup guides**. -1. Select **Observability**. -1. Select **Monitor my application performance**. -1. Scroll down and select the **OpenTelemetry** option. -1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there. - -Here's an example for sending data to an Elastic Cloud deployment: - -```sh -export OTEL_RESOURCE_ATTRIBUTES=service.name=,service.version=,deployment.environment=production -export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io -export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" -``` - -> [!NOTE] -> Alternatively on deployments, 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. -> -> To create and manage APM Agent keys in Kibana: -> -> 1. Go to **APM Settings**. -> 1. Select the **Agent Keys** tab. -> -> When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using different auth schema (`ApiKey` rather than `Bearer`). For example: -> ```sh -> export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ==" -> ``` - -And here's an example for sending data to an Elastic Cloud serverless project: - -```sh -export OTEL_RESOURCE_ATTRIBUTES=service.name=,service.version=,deployment.environment=production -export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io -export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey B....=" -``` - -> [!NOTE] -> You'll be prompted to create an API key during the Elastic Cloud serverless project onboarding. Refer to the [Api keys documentation](https://www.elastic.co/guide/en/serverless/current/api-keys.html) on how to manage them. - - -### Run EDOT Python - -Then wrap your service invocation with `opentelemetry-instrument`, which is the wrapper that provides _automatic instrumentation_: - -```bash -opentelemetry-instrument -``` - -For example, a web service running with gunicorn may look like this: - -```bash -opentelemetry-instrument gunicorn main:app -``` - - -## Confirm that EDOT Python is working - -To confirm that EDOT Python has successfully connected to Elastic: - -1. Go to **APM** → **Traces**. -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. -1. Click on the name in the list to see trace data. - -> [!NOTE] -> There may be no trace data to visualize unless you have _used_ your application since initializing EDOT Python. - - -## Next steps - -* See the [supported technologies](./supported-technologies.md). -* Reference all available [configuration options](./configure.md). -* Learn how to add [manual instrumentation](./manual-instrumentation.md). -* Learn more about viewing and interpreting data in the [Observability guide](https://www.elastic.co/guide/en/observability/current/apm.html). diff --git a/docs/manual-instrumentation.md b/docs/manual-instrumentation.md deleted file mode 100644 index 72b03915..00000000 --- a/docs/manual-instrumentation.md +++ /dev/null @@ -1,117 +0,0 @@ - - -# Manual instrumentation - -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. - -This guide requires to have already added autoinstrumentation with OpenTelemetry to your application per [Get started](./get-started.md). - -**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. - - -### Configure EDOT Python - -To configure EDOT Python, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and -authorization data to set a few `OTLP_*` environment variables that will be available when running EDOT Python: - -```sh -export OTEL_RESOURCE_ATTRIBUTES=service.name= -export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io -export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" -``` - -Refer to our [get started](./get-started.md) page for more details. - - -### Manually instrument your auto instrumented Python application - -In this section we'll show how to add manual instrumentation to an already automatically instrumented application. A use case for -this setup would be to trace something in particular while keeping the benefits of the simplicity of the automatic instrumentation doing -the hard work for us. - -As an example we'll use an application using the Flask framework that implements an endpoint mounted on `/hello` returning a friendly -salute. This application is saved in a file named `app.py` that is the default module for Flask applications. - -``` -import random - -from flask import Flask -from opentelemetry import trace - -tracer = trace.get_tracer(__name__) - -app = Flask(__name__) - -@app.route("/hello") -def hello(): - choices = ["there", "world", "folks", "hello"] - # create a span for the choice of the name, this may be a costly call in your real world application - with tracer.start_as_current_span("choice") as span: - choice = random.choice(choices) - span.set_attribute("choice.value", choice) - return f"Hello {choice}!" -``` - -We need to make sure to have Flask and the Flask OpenTelemetry instrumentation installed: - -```bash -pip install flask -edot-bootstrap --action=install -``` - -And then we can run this application with the following command: - -```bash -opentelemetry-instrument flask run -``` - -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 -are tracking how many times we are getting one of the possible choices for our salutes. - -``` -import random - -from flask import Flask -from opentelemetry import metrics, trace - -tracer = trace.get_tracer(__name__) -meter = metrics.get_meter(__name__) - -hello_counter = meter.create_counter( - "hello.choice", - description="The number of times a salute is chosen", -) - -app = Flask(__name__) - -@app.route("/hello") -def hello(): - choices = ["there", "world", "folks", "hello"] - # create a span for the choice of the name, this may be a costly call in your real world application - with tracer.start_as_current_span("choice") as span: - choice = random.choice(choices) - span.set_attribute("choice.value", choice) - hello_counter.add(1, {"choice.value": choice}) - return f"Hello {choice}!" -``` - - -## Confirm that EDOT Python is working - -To confirm that EDOT Python has successfully connected to Elastic: - -1. Go to **APM** → **Traces**. -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. -1. Click on the name in the list to see trace data. - -> [!NOTE] -> There may be no trace data to visualize unless you have _used_ your application since initializing EDOT Python. - - -## Next steps - -* Reference all available [configuration options](./configure.md). -* Learn more about viewing and interpreting data in the [Observability guide](https://www.elastic.co/guide/en/observability/current/apm.html). diff --git a/docs/migrate-from-apm.md b/docs/migrate-from-apm.md deleted file mode 100644 index c1776674..00000000 --- a/docs/migrate-from-apm.md +++ /dev/null @@ -1,69 +0,0 @@ - - -# Compare EDOT Python and the Elastic APM Python agent - -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). -For step-by-step instructions on setting up EDOT Python refer to the [Get started guide](./get-started.md). - -## We are a distribution - -As a distribution of OpenTelemetry, EDOT Python follows certain standards, but there is still some space for innovation. - -## Bold on autoinstrumentation - -We have chosen to make autoinstrumentation 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). - -## Bring your own instrumentation - -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. -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). - -## Limitations - -### Central and Dynamic configuration - -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. - -### AWS lambda - -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/). - -### Missing instrumentations - -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. - -At the time of writing these docs, the following libraries are missing an OpenTelemetry instrumentation: -- aiobotocore -- aiomysql -- aiopg -- aioredis -- Azure storage and Azure queue -- Graphene -- httplib2 -- pylibmc -- pyodbc -- pymssql -- Sanic -- zlib - -### Integration with structured logging - -EDOT Python does not have any [structlog integration](https://www.elastic.co/guide/en/apm/agent/python/current/logs.html#structlog) at the moment. - -### Span compression - -EDOT Python does not implement [span compression](https://www.elastic.co/guide/en/observability/current/apm-data-model-spans.html#apm-spans-span-compression). - -### Breakdown metrics - -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). - - -## Next steps - -* [Get started](./get-started.md) with EDOT Python. -* Learn how to add [manual instrumentation](./manual-instrumentation.md). -* Learn more about viewing and interpreting data in the [Observability guide](https://www.elastic.co/guide/en/observability/current/apm.html). diff --git a/docs/supported-technologies.md b/docs/supported-technologies.md deleted file mode 100644 index 598bd414..00000000 --- a/docs/supported-technologies.md +++ /dev/null @@ -1,96 +0,0 @@ - - -# Supported technologies - -## Elastic Stack versions - -The Elastic Distribution of OpenTelemetry Python (EDOT Python) sends data via OpenTelemetry protocol (OTLP). -It is strongly recommended to be using at least a recent 8.x version of the Elastic Observability Stack. - -On [Elastic Cloud](https://www.elastic.co/cloud) both hosted deployments of the Elastic Stack and [Serverless](https://www.elastic.co/cloud/serverless) projects are supported. - -## Python versions - -The following Python versions are supported: - - * 3.8 - * 3.9 - * 3.10 - * 3.11 - * 3.12 - * 3.13 - -This follows the [OpenTelemetry Python Version Support](https://github.com/open-telemetry/opentelemetry-python/?tab=readme-ov-file#python-version-support). - -## Instrumentations - -We don't install instrumentations by default and we suggest to use our [edot-bootstrap](../get-started.md#install-the-available-instrumentation) command to automatically install the available instrumentations. - -| Name | Packages instrumented | Semantic conventions status | -|---|---|---|---| -| [elastic-opentelemetry-instrumentation-openai](https://github.com/elastic/elastic-otel-python-instrumentations/blob/main/instrumentation/elastic-opentelemetry-instrumentation-openai) | openai >= 1.2.0 | development -| [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-aiohttp-client](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-aiohttp-client) | aiohttp ~= 3.0 | migration -| [opentelemetry-instrumentation-aiohttp-server](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-aiohttp-server) | aiohttp ~= 3.0 | development -| [opentelemetry-instrumentation-aiokafka](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-aiokafka) | aiokafka >= 0.8, < 1.0 | development -| [opentelemetry-instrumentation-aiopg](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-aiopg) | aiopg >= 0.13.0, < 2.0.0 | development -| [opentelemetry-instrumentation-asgi](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-asgi) | asgiref ~= 3.0 | migration -| [opentelemetry-instrumentation-asyncio](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-asyncio) | asyncio | development -| [opentelemetry-instrumentation-asyncpg](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-asyncpg) | asyncpg >= 0.12.0 | development -| [opentelemetry-instrumentation-aws-lambda](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-aws-lambda) | | development -| [opentelemetry-instrumentation-boto](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-boto) | boto~=2.0 | development -| [opentelemetry-instrumentation-boto3sqs](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-boto3sqs) | boto3 ~= 1.0 | development -| [opentelemetry-instrumentation-botocore](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-botocore) | botocore ~= 1.0 | development -| [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 -| [opentelemetry-instrumentation-celery](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-celery) | celery >= 4.0, < 6.0 | development -| [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 -| [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 -| [opentelemetry-instrumentation-dbapi](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-dbapi) | dbapi | development -| [opentelemetry-instrumentation-django](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-django) | django >= 1.10 | development -| [opentelemetry-instrumentation-elasticsearch](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-elasticsearch) | elasticsearch >= 6.0 | development -| [opentelemetry-instrumentation-falcon](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-falcon) | falcon >= 1.4.1, < 5.0.0 | migration -| [opentelemetry-instrumentation-fastapi](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-fastapi) | fastapi ~= 0.58 | migration -| [opentelemetry-instrumentation-flask](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-flask) | flask >= 1.0 | migration -| [opentelemetry-instrumentation-grpc](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-grpc) | grpcio >= 1.42.0 | development -| [opentelemetry-instrumentation-httpx](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-httpx) | httpx >= 0.18.0 | migration -| [opentelemetry-instrumentation-jinja2](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-jinja2) | jinja2 >= 2.7, < 4.0 | development -| [opentelemetry-instrumentation-kafka-python](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-kafka-python) | kafka-python >= 2.0, < 3.0,kafka-python-ng >= 2.0, < 3.0 | development -| [opentelemetry-instrumentation-logging](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-logging) | logging | development -| [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 -| [opentelemetry-instrumentation-mysqlclient](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-mysqlclient) | mysqlclient < 3 | development -| [opentelemetry-instrumentation-pika](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pika) | pika >= 0.12.0 | development -| [opentelemetry-instrumentation-psycopg](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-psycopg) | psycopg >= 3.1.0 | development -| [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 -| [opentelemetry-instrumentation-pymemcache](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymemcache) | pymemcache >= 1.3.5, < 5 | development -| [opentelemetry-instrumentation-pymongo](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymongo) | pymongo >= 3.1, < 5.0 | development -| [opentelemetry-instrumentation-pymssql](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymssql) | pymssql >= 2.1.5, < 3 | development -| [opentelemetry-instrumentation-pymysql](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pymysql) | PyMySQL < 2 | development -| [opentelemetry-instrumentation-pyramid](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-pyramid) | pyramid >= 1.7 | development -| [opentelemetry-instrumentation-redis](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-redis) | redis >= 2.6 | development -| [opentelemetry-instrumentation-remoulade](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-remoulade) | remoulade >= 0.50 | development -| [opentelemetry-instrumentation-requests](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests) | requests ~= 2.0 | migration -| [opentelemetry-instrumentation-sqlalchemy](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-sqlalchemy) | sqlalchemy >= 1.0.0, < 2.1.0 | development -| [opentelemetry-instrumentation-sqlite3](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-sqlite3) | sqlite3 | development -| [opentelemetry-instrumentation-starlette](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-starlette) | starlette >= 0.13, <0.15 | development -| [opentelemetry-instrumentation-system-metrics](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-system-metrics) | psutil >= 5 | development -| [opentelemetry-instrumentation-threading](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-threading) | threading | development -| [opentelemetry-instrumentation-tornado](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-tornado) | tornado >= 5.1.1 | development -| [opentelemetry-instrumentation-tortoiseorm](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-tortoiseorm) | tortoise-orm >= 0.17.0 | development -| [opentelemetry-instrumentation-urllib](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib) | urllib | migration -| [opentelemetry-instrumentation-urllib3](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-urllib3) | urllib3 >= 1.0.0, < 3.0.0 | migration -| [opentelemetry-instrumentation-wsgi](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-wsgi) | wsgi | migration - -The semantic conventions status tracks the stabilization of the semantic conventions used in the instrumentation: -- stable, means they are stable and are not expected to change -- development, means they are not stable yet and they may change in the future -- migration, means there may be configuration knobs to switch between different semantic conventions - -### Native Elasticsearch instrumentation - -Some libraries like the [Python Elasticsearch Client](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html) -natively supports OpenTelemetry instrumentation. - -The [elasticsearch](https://elasticsearch-py.readthedocs.io/en/latest/) package got native OpenTelemetry support since version 8.13. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index a9cedb31..00000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -1,56 +0,0 @@ - - -# Troubleshooting - -Below are some resources and tips for troubleshooting and debugging the Elastic Distribution of OpenTelemetry Python (EDOT Python). - -- [Easy Fixes](#easy-fixes) -- [Disable EDOT](#easy-fixes) - -## Easy Fixes - -Before you try anything else, go through the following sections to ensure that -EDOT Python is configured correctly. This is not an exhaustive list, but rather -a list of common problems that users run into. - -### Debug and development modes - -Most frameworks support a debug mode. Generally, this mode is intended for -non-production environments and provides detailed error messages and logging of -potentially sensitive data. So enabling instrumentation in debug mode is not advised and may pose privacy and security issues in recording -sensitive data. - -#### Django - -Django applications running with the Django `runserver` need to use the `--noreload` parameter in order to be instrumented with `opentelemetry-instrument`. -Remember that you also need to set the `DJANGO_SETTINGS_MODULE` environment variable pointing to the application settings module. - -#### FastAPI - -FastAPI application started with `fastapi dev` requires the reloader to be disabled with `--no-reload` in order to be instrumented with `opentelemetry-instrument`. - -#### Flask - -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). - -## Disable EDOT - -In the unlikely event EDOT Python causes disruptions to a production application, you can disable it while you troubleshoot. - -To disable the underlying OpenTelemetry SDK you set the following environment variable `OTEL_SDK_DISABLED=true`. - -If only a subset of instrumentation are causing disruptions you can disable them with the `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` -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) - -## Missing logs - -Enabling the Python logging module auto-instrumentation with `OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true` calls the -[logging.basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig) method that will make your own application calls -to it a no-op. The side effect of this is that you won't see your application logs in the console anymore. - -If you are already shipping logs by other means you don't need to enable this. - -