diff --git a/README.md b/README.md index 64d41e2..889362e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,35 @@ -# elastic-opentelemetry -- Elastic Distribution of OpenTelemetry Python +# Elastic Distribution of OpenTelemetry Python -`elastic-opentelemetry` is the Elastic Distribution of OpenTelemetry Python. +> [!WARNING] +> The Elastic Distribution of OpenTelemetry Python is not yet recommended for production use. Functionality may be changed or removed in future releases. Alpha releases are not subject to the support SLA of official GA features. +> +> We welcome your feedback! You can reach us by [opening a GitHub issue](https://github.com/elastic/elastic-otel-python/issues) or starting a discussion thread on the [Elastic Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/python). -## Installation +The Elastic Distribution of OpenTelemetry Python (EDOT Python) is a customized version of [OpenTelemetry Python](https://opentelemetry.io/docs/languages/python). +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 introduce **no new concepts** in addition to those defined by the wider OpenTelemetry community. + +With EDOT Python you have access to all the features of the OpenTelemetry Python agent plus: + +* Access to improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories. +* Access to optional features that can enhance OpenTelemetry data that is being sent to Elastic. +* 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) +* [Configuration](./docs/configure.md) + +## Install ```bash pip install elastic-opentelemetry ``` + + ## Usage Our distribution does not install any instrumentation package by default, instead it relies on the diff --git a/docs/configure.md b/docs/configure.md new file mode 100644 index 0000000..e935177 --- /dev/null +++ b/docs/configure.md @@ -0,0 +1,50 @@ + + +# 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). + +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` | `otel` | + + +### 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 new file mode 100644 index 0000000..ee387d6 --- /dev/null +++ b/docs/get-started.md @@ -0,0 +1,132 @@ + + +# 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 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`). +
+ + +## 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 +`opentelemetry-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 +opentelemetry-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 deployment's 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: + +```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" +``` + +> [!NOTE] +> 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. +> +> 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==" +> ``` + + +### 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 + +* 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).