Skip to content

Commit

Permalink
docs: add serverless setup instruction to get started (#257)
Browse files Browse the repository at this point in the history
* docs: add serverless setup instruction to get started

* Better handling for serverless
  • Loading branch information
xrmx authored Mar 10, 2025
1 parent d77482e commit 6c0137e
Showing 1 changed file with 27 additions and 5 deletions.
32 changes: 27 additions & 5 deletions docs/get-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ This guide shows you how to use the Elastic Distribution of OpenTelemetry Python
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.

<details>
<summary><strong>Expand for setup instructions</strong></summary>
<summary><strong>Expand for Elastic Observability deployment setup instructions</strong></summary>

To create your first Elastic Observability deployment:

Expand All @@ -28,6 +28,17 @@ To create your first Elastic Observability 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`).
</details>

<details>
<summary><strong>Expand for Elastic Observability Serverless setup instructions</strong></summary>

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 <https://cloud.elastic.co/home>.
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`).
</details>

<!-- ✅ How to install EDOT Python -->
## Install

Expand Down Expand Up @@ -61,7 +72,7 @@ After installing EDOT Python, configure and initialize it to start sending data
<!-- ✅ Provide _minimal_ configuration/setup -->
### Configure EDOT Python

To configure EDOT Python, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and
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.
Expand All @@ -77,16 +88,16 @@ You can find the values of the endpoint and header variables in Kibana's APM tut
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:
Here's an example for sending data to an Elastic Cloud deployment:

```sh
export OTEL_RESOURCE_ATTRIBUTES=service.name=<app-name>
export OTEL_RESOURCE_ATTRIBUTES=service.name=<app-name>,service.version=<app-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, 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.
> 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:
>
Expand All @@ -98,6 +109,17 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l"
> 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=<app-name>,service.version=<app-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.
<!-- ✅ Start sending data to Elastic -->
### Run EDOT Python
Expand Down

0 comments on commit 6c0137e

Please sign in to comment.