This topic explains how to install OpenTelemetry and export the trace data to Lightstep.

Requirements

  • Python 3.4 or newer
  • A Lightstep account. If you don’t already have one, you can create a free account here.
  • An Access Token for the Lightstep project you would like to use.
  • An app to add OpenTelemetry to. You can use this one or use your own.

Install OpenTelemetry

To use OpenTelemetry, you need to install the auto-instrumentation and sdk packages for Python. The version of the auto-instrumentation and sdk used in this guide is 0.7b1.

Install using pip:

1
pip install opentelemetry-auto-instrumentation opentelemetry-sdk

To connect OpenTelemetry to Lightstep, also install the Lightstep exporter:

1
pip install opentelemetry-ext-lightstep

Configure OpenTelemetry

The following code block will set up OpenTelemetry and connect it to LightStep.

Start tabs

Public Satellites

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#!/usr/bin/env python3
# server.py

from opentelemetry import trace
from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
from opentelemetry.ext.lightstep import LightstepSpanExporter

exporter = LightstepSpanExporter(
  name="<YOUR SERVICE NAME HERE>",
  token="<YOUR ACCESS TOKEN HERE>",
  service_version="<YOUR SERVICE VERSION HERE E.G. 1.2.3>",
)

tracer = trace.get_tracer(__name__)
span_processor = BatchExportSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)


if __name__ == "__main__":
   ...

On-Premise Satellites

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
#!/usr/bin/env python3
# server.py

from opentelemetry import trace
from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
from opentelemetry.ext.lightstep import LightstepSpanExporter

exporter = LightstepSpanExporter(
  name="<YOUR SERVICE NAME HERE>",
  token="<YOUR ACCESS TOKEN HERE>",
  host="<SATELLITE_URL>",
  port="<SATELLITE_PORT>",
  service_version="<YOUR SERVICE VERSION HERE E.G. 1.2.3>",
)

tracer = trace.get_tracer(__name__)
span_processor = BatchExportSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)


if __name__ == "__main__":
   ...

Developer Mode

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
#!/usr/bin/env python3
# server.py

from opentelemetry import trace
from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
from opentelemetry.ext.lightstep import LightstepSpanExporter

exporter = LightstepSpanExporter(
  name="<YOUR SERVICE NAME HERE>",
  token="developer",
  host="localhost",
  service_version="<YOUR SERVICE VERSION HERE E.G. 1.2.3>",
)

tracer = trace.get_tracer(__name__)
span_processor = BatchExportSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)


if __name__ == "__main__":
   ...

End code tabs

Install Instrumentation Libraries

Frameworks, database clients, and other 3rd party libraries contain critical data. The fastest and most effective way to instrument your application is to install instrumentation libraries. Often, this is enough instrumentation to get started. The example application relies on the Flask and requests libraries, the following commands installs the instrumentation libraries for each one:

1
2
pip install opentelemetry-ext-flask
pip install opentelemetry-ext-requests

All current instrumentation can be found on Github. Available instrumentation includes:

Don’t see support for your framework or library? Join the beta by filing an issue, or try your hand at writing an instrumentation adapter yourself!

Run OpenTelemetry

The opentelemetry-auto-instrumentation script loads all installed instrumentation libraries before your application runs, giving it a chance to instrument any calls to supported libraries. Start the application:

1
2
export OPENTELEMETRY_PYTHON_tracer_provider=sdk_tracer_provider
opentelemetry-auto-instrumentation python3 walkthrough/server.py

View Traces in Lightstep

Now that your app is running, you can view the telemetry data in Lightstep.

  1. Trigger an action in your app that generates a web request.

  2. In Lightstep, click on the Explorer view. Explorer view

  3. Click on any span in the Trace Analysis table. Spans in the Trace Analysis table

  4. View the trace and any metadata produced by the telemetry. Trace view

Learn more about using Lightstep by following one of our learning paths.

Troubleshooting

Check that the exporter was installed

If OpenTelemetry and the Lightstep exporter are correctly installed, the following lines will be printed to the console:

1
2
3
4
5
6
7
8
pip freeze | grep opentelemetry
opentelemetry-api==0.7b1
opentelemetry-auto-instrumentation==0.7b1
opentelemetry-ext-flask==0.7b1
opentelemetry-ext-lightstep==0.7b0
opentelemetry-ext-requests==0.7b1
opentelemetry-ext-wsgi==0.7b1
opentelemetry-sdk==0.7b1

Logging to the console

If you are not seeing any data, you can verify that spans are being created by using the ConsoleSpanExporter to view the data in your console.

1
2
3
4
from opentelemetry.sdk.trace.export import ConsoleSpanExporter

console_span_processor = BatchExportSpanProcessor(ConsoleSpanExporter())
trace.get_tracer_provider().add_span_processor(console_span_processor)