Skip to content

Latest commit

 

History

History
133 lines (95 loc) · 5.96 KB

get-started.md

File metadata and controls

133 lines (95 loc) · 5.96 KB
Raw

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.

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 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 or sign into an existing account.
  2. Go to https://cloud.elastic.co/home.
  3. Click Create deployment.
  4. 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:

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:

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.
  2. Select Observability.
  3. Select Monitor my application performance.
  4. Scroll down and select the OpenTelemetry option.
  5. The appropriate values for OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS are shown there.

Here's an example:

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"

Note

Alternatively, you can use an APM agent key 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.
  2. 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:

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:

opentelemetry-instrument <command to start your service>

For example, a web service running with gunicorn may look like this:

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.
  2. 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.
  3. 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