If your app is written in Python, you can get started quickly with Lightstep. Download the Auto-Installer, then configure it to communicate with your Lightstep Satellites. When you deploy your app, all supported frameworks, data stores, and libraries will begin sending trace data to Lightstep. The Lightstep tracer also collects and reports on machine metrics, communicating directly with the Lightstep Engine.

To ensure you can access all Lightstep functionality, including machine metrics reporting, update your tracer to the latest release. To update, simply follow the instructions for installing the tracer. No code changes are needed.

These Auto-Installers are forked from Datadog’s contribution of their tracers to the OpenTelemetry project. You can find the original Datadog docs here.

For Python Django applications, note that tracing is disabled when your application is launched in DEBUG mode.

Supported Python Versions

Python versions 2.7 and 3.4 and up are supported.

Install the Auto-Installer

Install the Python Auto-Installer, using pip.

1
pip install ls-trace

Import Tracer and Set B3 Headers for Trace Propagation

Lightstep recommends using B3 headers for trace propagation as the default, especially on hybrid deployments, as it is the most widely supported header at this time.

1
2
3
from ddtrace import tracer
from ddtrace.propagation.b3 import B3HTTPPropagator
tracer.configure(http_propagator=B3HTTPPropagator)

Configure the Auto-Installer to Send Data to Lightstep

To send data from your system to Lightstep, you need to configure the Auto-Installer to:

  • Point to your Satellites
  • Send global tags required by Lightstep to ingest and display the data to you.

To configure the Auto-Installer:

Configure the Auto-Installer to point to the Lightstep Satellites by setting these environment variables. Use the right values, depending on if you are using on-premise, Lightstep public, or Developer Mode Satellites.

Start tabs

On-Premise Satellites

1
2
DD_TRACE_AGENT_URL=https://<Satellite host>:<Satellite port>
DD_TRACE_GLOBAL_TAGS=lightstep.service_name:<service_name>,lightstep.access_token:<access_token>

Public Satellites

1
2
DD_TRACE_AGENT_URL=https://ingest.lightstep.com:443
DD_TRACE_GLOBAL_TAGS=lightstep.service_name:<service_name>,lightstep.access_token:<access_token>

Developer Mode

1
2
DD_TRACE_AGENT_URL=http://localhost:8360
DD_TRACE_GLOBAL_TAGS=lightstep.service_name:<service_name>,lightstep.access_token:developer

End code tabs

The host and port values for on-premise Satellites is your pool address, found in your configuration file.

When setting the environment variable DD_TRACE_GLOBAL_TAGS, the following variables must be included:

  • service_name:
    The name of the service from which spans originate. This tag allows Lightstep to accurately report on your services, with features such as the Service diagram and the Service Directory
  • access_token:
    The access token for the project the tracers report to. Lightstep Satellites need this token to accept and store span data from the tracer. Reports from clients with invalid or deactivated access tokens will be rejected on ingress.

Configure Metrics Reporting

Along with the tracer collecting telemetry data to report on performance issues and other contextual information to help you with root cause analysis, Lightstep can also ingest and report on machine runtime metrics for a service to further assist in your investigations.

To ensure you can access all Lightstep functionality, including machine metrics reporting, update your tracer to the latest release. To update, simply follow the instructions for installing the tracer. No code changes are needed.

The following machine metrics are sent to Lightstep:

  • CPU Usage (%)
  • Memory (%)
  • Network (bytes)

  • Garbage Collection (GC) Cycles (count)

These metrics are displayed when you compare performance of a service over two different time periods.

Machine metrics are enabled by default. However, if you use a proxy, you need to set this environment variable to point to the Lightstep endpoint. LS_METRICS_URL=http://localhost:8126/metrics
or
LS_METRICS_URL=<scheme>://<proxy_host>:<proxy_port>/metrics

If you don’t want metrics reported, you can configure the auto-installer to turn it off.

To turn metrics off:

Set the following environment variable:
LS_METRICS_ENABLED=False

Run Your App

To include the Auto-Installer’s auto-instrumentation, prefix your Python entry-point command with ls-trace-run.
For example, if your application is started with python app.py then:
$ ls-trace-run python app.py

What’s Auto-Instrumented

Following are the supported frameworks, data stores, and libraries that are auto-instrumented when you run your app.

Frameworks

FrameworkSupported Version
aiohttp>= 1.2
Bottle>= 0.11
Django>= 1.8
djangorestframework>= 3.4
Falcon>= 1.0
Flask>= 0.10
Molten>= 0.7.0
Pylons>= 0.9.6
Pyramid>= 1.7
Tornado>= 4.0

Data Stores

DatastoreSupported Version
Cassandra>= 3.5
Elasticsearch>= 1.6
Flask Cache>= 0.12
Memcached pylibmc>= 1.4
Memcached pymemcache>= 1.3
MongoDB Mongoengine>= 0.11
MongoDB Pymongo>= 3.0
MySQL MySQL-python>= 1.2.3
MySQL mysqlclient>= 1.3
MySQL mysql-connector>= 2.1
Postgres aiopg>= 0.12.0
Postgres psycopg>= 2.4
Redis>= 2.6
Redis redis-py-cluster>= 1.3.5
SQLAlchemy>= 1.0
SQLite3Fully Supported
Vertica>= 0.6

Libraries

LibrarySupported Version
asyncioFully Supported
gevent>= 1.0
aiobotocore>= 0.2.3
Boto2>= 2.29.0
Botocore>= 1.4.51
Celery>= 4.0.2
FuturesFully Supported
Grpc>= 1.8.0
httplibFully Supported
Jinja2>= 2.7
Kombu>= 4.0
Mako>= 0.1.0
Requests>= 2.08

Use Datadog Tracers with Lightstep Tracers

If you’re using a mix of Datadog and Lightstep you must use B3 header propagation.