Skip to content

[docs] Prepare minimal viable docs #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Sep 5, 2024
Merged

[docs] Prepare minimal viable docs #110

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bcb89f0
initial draft
colleenmcginnis Aug 22, 2024
5973733
address feedback
colleenmcginnis Aug 23, 2024
baee8a7
address more feedback
colleenmcginnis Aug 26, 2024
79b1ed8
Update docs/configure.md
xrmx Sep 3, 2024
19a88fa
Update docs/get-started.md
xrmx Sep 3, 2024
03d2c98
Merge branch 'main' into prep-docs
xrmx Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 2 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,15 @@
>
> 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).

<!--
Is the Python distro built on top of the OTel Python agent (https://opentelemetry.io/docs/zero-code/python/)?
Or the OTel Python SDK (https://opentelemetry.io/docs/languages/python/)?
Or neither?
-->
The Elastic Distribution of OpenTelemetry Python (EDOT Python) is a customized version of the [OpenTelemetry SDK for Python](https://opentelemetry.io/docs/languages/python).
<!-- Is this true of the Python distro? -->
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:

<!--
These are some examples from other distro docs.
Feel free to delete or edit these items or add new items to this list.
-->
* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories.
* 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.
* Ensuring that the OpenTelemetry protocol (OTLP) exporter is enabled by default.

**Ready to try out EDOT Python?** Follow the step-by-step instructions in [Get started](./docs/get-started.md).

Expand Down
37 changes: 10 additions & 27 deletions docs/configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,58 +9,41 @@ General OpenTelemetry configuration options are linked.

Configure the Elastic Distribution of OpenTelemetry Python (EDOT Python) to send data to Elastic.

<!-- How users set configuration options -->
<!-- ✅ How users set configuration options -->
## Configuration method

<!-- Is this the right link to OpenTelemetry docs? -->
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:

<!-- Would this example work? -->
```sh
export OTEL_RESOURCE_ATTRIBUTES=service.name=<app-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 <command to start your service>
```

<!-- List all available configuration options -->
<!-- ✅ List all available configuration options -->
## Configuration options

<!-- Is the distro an extension of the OTel Python SDK? The agent? Or neither? -->
Because the Elastic Distribution of OpenTelemetry Python is an extension of the OpenTelemetry Python SDK, it supports:
Because the Elastic Distribution of OpenTelemetry Python is an extension of OpenTelemetry Python, it supports both:

* [OpenTelemetry configuration options](#opentelemetry-configuration-options)
* [Configuration options that are _only_ available in EDOT Python](#configuration-options-that-are-only-available-in-edot-python)
* [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 SDK](https://opentelemetry.io/docs/languages/python).
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).

<!-- Is this true? Or did you list these in the README for some other reason? -->
EDOT Python uses different defaults than the OpenTelemetry Python SDK for the following configuration options:
EDOT Python uses different defaults than OpenTelemetry Python for the following configuration options:

| Option | EDOT Python default | OpenTelemetry Python agent default |
| Option | EDOT Python default | OpenTelemetry Python default |
|---|---|---|
| `OTEL_TRACES_EXPORTER` | `otlp` | ?? ([docs](#)) |
| `OTEL_METRICS_EXPORTER` | `otlp` | ?? ([docs](#)) |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc` | ?? ([docs](#)) |
| `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` | `process_runtime,otel,telemetry_distro` | ?? ([docs](#)) |
| `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` | `process_runtime,otel,telemetry_distro` | N/A |


### Configuration options that are _only_ available in EDOT Python

In addition to general OpenTelemetry configuration options, there are two kinds of configuration options that are _only_ available in EDOT Python.

<!-- This is true for the Java distro, is it also true of the Python distro? -->
**Elastic-authored options that are not yet available upstream**

Additional `OTEL_` options that Elastic plans to contribute upstream to the OpenTelemetry Python SDK, but are not yet available in the OpenTelemetry Python SDK.

_Currently there are no additional `OTEL_` options waiting to be contributed upstream._

**Elastic-specific options**

`ELASTIC_OTEL_` options that are specific to Elastic and will always live in EDOT Python (in other words, they will _not_ be added upstream):
`ELASTIC_OTEL_` options are specific to Elastic and will always live in EDOT Python (they will _not_ be added upstream):

| Option(s) | Default | Description |
|---|---|---|
Expand Down
21 changes: 17 additions & 4 deletions docs/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,9 @@ This guide shows you how to use the Elastic Distribution of OpenTelemetry Python

**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/zero-code/python/agent/).
**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/).

<!-- What the user needs to know and/or do before they install EDOT Python -->
<!-- Is this missing anything? -->
<!-- ✅ What the user needs to know and/or do before they install EDOT 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 Down Expand Up @@ -91,6 +90,21 @@ export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.
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_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
> export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ=="
> ```

<!-- ✅ Start sending data to Elastic -->
### Run EDOT Python

Then wrap your service invocation with `opentelemetry-instrument`, which is the wrapper that provides _automatic instrumentation_:
Expand All @@ -114,7 +128,6 @@ To confirm that EDOT Python has successfully connected to Elastic:
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.

<!-- Is this true for the Python distro? -->
> [!NOTE]
> There may be no trace data to visualize unless you have _used_ your application since initializing EDOT Python.

Expand Down