Setup and Install OpenTelemetry Python

Get up and running with OpenTelemetry in just a few quick steps! The setup process consists of two phases--getting OpenTelemetry installed and configured, and then validating that configuration to ensure that data is being sent as expected. This guide explains how to download, install, and run OpenTelemetry in Python.

Requirements

  • Python 3.4 or newer
  • An app to add OpenTelemetry to. You can use this example application or bring your own.
  • A Lightstep account, or another OpenTelemetry backend.

Need an account? Create a free Lightstep account here.

Installation

To install OpenTelemetry, we recommend our handy OTel-Launcher, which simplifies the process.

Installing the launcher using pip:

pip install opentelemetry-launcher

It is also important to install instrumentation for your frameworks and libararies. Once the launcher is install, you can run opentelemetry-bootstrap to automatically detect supported libraries and install the associated instrumentation.

opentelemetry-bootstrap --action=install

Run OpenTelemetry

Once you've installed the launcher and instrumentation packages, you can now add OpenTelemetry to your service.

LS Note: When connecting to Lightstep, a project Access Token is required.

When auto-instrumenting, all configuration parameters must be passed as environment variables. The following configuration options are required.

export LS_ACCESS_TOKEN="<ACCESS TOKEN>"
export LS_SERVICE_NAME="<SERVICE NAME>"
export OTEL_PROPAGATORS="b3,baggage"
export OTEL_PYTHON_TRACER_PROVIDER=sdk_tracer_provider

The full list of configuration options can be found in the README.

Once you've set up your environent, you can run your application via the opentelemetry-instrument command.

opentelemetry-instrument python my_service.py

opentelemetry-instrument automatically integrates the opentelemetry launcher and library instrumentation into your application.

Validate Installation

With your application running, you can now verify that you’ve installed OpenTelemetry correctly by confirming that telemetry data is being reported to your observability backend.

To do this, you need to make sure that your application is actually generating data. Applications will generally not produce traces unless they are being interacted with, and opentelemetry will often buffer data before sending it. So it may take some amount of time and interaction before your application data begins to appear in your backend.

Validate your traces in Lightstep:

  1. Trigger an action in your app that generates a web request.
  2. In Lightstep, click on the Explorer in the sidebar.
  3. Refresh your query until you see traces.
  4. View the traces and verify that important aspects of your application are captured by the trace data.

OpenTracing Support

The OpenTracing shim allows existing OpenTracing instrumentation to report to the OpenTelemetry SDK. OpenTracing support is not enabled by default. Instructions for enabling the shim can be found in the README.

pip install opentelemetry-opentracing-shim

Read more about upgrading to OpenTelemetry in our OpenTracing Migration Guide.

Troubleshooting

Having trouble with installation? Check the following tips.

Run the launcher in debug mode

If spans are not being reported to Lightstep, try running in debug mode by setting OTEL_LOG_LEVEL=debug:

OTEL_LOG_LEVEL=debug node first-tracer.js

The debug log level will print out the configuration information. Check to ensure that your access token looks correct. It will also emit every span to the console, which should look something like:

Span {
  attributes: {},
  links: [],
  events: [],
  status: { code: 0 },
  endTime: [ 1597810686, 885498645 ],
  _ended: true,
  _duration: [ 0, 43333 ],
  name: 'bar',
  spanContext: {
    traceId: 'eca3cc297720bd705e734f4941bca45a',
    spanId: '891016e5f8c134ad',
    traceFlags: 1,
    traceState: undefined
  },
  parentSpanId: 'cff3a2c6bfd4bbef',
  kind: 0,
  startTime: [ 1597810686, 885455312 ],
  resource: Resource { labels: [Object] },
  instrumentationLibrary: { name: 'example', version: '*' },
  _logger: ConsoleLogger {
    debug: [Function],
    info: [Function],
    warn: [Function],
    error: [Function]
  },
  _traceParams: {
    numberOfAttributesPerSpan: 32,
    numberOfLinksPerSpan: 32,
    numberOfEventsPerSpan: 128
  },
  _spanProcessor: MultiSpanProcessor { _spanProcessors: [Array] }
},

Ensure gcc and gcc-c++ are installed

Compiling the grpc packages requires gcc and gcc-c++, which may need to be installed manually:

$ yum -y install python3-devel
$ yum -y install gcc-c++