docs: Add troubleshooting page

README.md

@@ -24,6 +24,7 @@ With EDOT Python you have access to all the features of the OpenTelemetry Python
 * [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
 

docs/configure.md

@@ -36,12 +36,15 @@ EDOT Python supports all configuration options listed in the [OpenTelemetry Gene
 
 #### Logs
 
-Exporting logs from the Python `logging` module is disabled by default and gated under a configuration environment variable:
+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:

docs/troubleshooting.md

@@ -0,0 +1,56 @@
+<!--
+Goal of this doc:
+The user is able to overcome on their own some basic issues
+-->
+
+# 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.
+
+<!-- TODO: when available add link to to propose other option  https://elastic.github.io/opentelemetry/use-cases/logs/ -->