Install & Compatibility
Where this runs
tested against v4.4.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Tracer
✓ from lightstep import Tracer
✗ import lightstep
This quickstart demonstrates how to send traces to Lightstep/Cloud Observability using the recommended OpenTelemetry Python SDK. It configures a `TracerProvider` with an `OTLPSpanExporter` and sets up basic manual instrumentation. Ensure `LS_ACCESS_TOKEN` and `OTEL_SERVICE_NAME` environment variables are set. For non-development environments, using an OpenTelemetry Collector is highly recommended.
import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
# --- Configuration (using environment variables for security) ---
LS_ACCESS_TOKEN = os.environ.get('LS_ACCESS_TOKEN', 'YOUR_LIGHTSTEP_ACCESS_TOKEN')
SERVICE_NAME = os.environ.get('OTEL_SERVICE_NAME', 'my-python-app')
OTLP_ENDPOINT = os.environ.get('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT', 'ingest.lightstep.com:443')
# Configure resource
resource = Resource.create({"service.name": SERVICE_NAME})
# Configure tracer provider
provider = TracerProvider(resource=resource)
# Configure OTLP exporter for Lightstep
otlp_exporter = OTLPSpanExporter(
endpoint=OTLP_ENDPOINT,
headers={
"lightstep-access-token": LS_ACCESS_TOKEN
},
# Optionally, if using a collector without TLS, set insecure=True
# insecure=True
)
# Configure console exporter for local debugging
console_exporter = ConsoleSpanExporter()
# Add span processors
provider.add_span_processor(SimpleSpanProcessor(otlp_exporter))
provider.add_span_processor(SimpleSpanProcessor(console_exporter))
# Set the global tracer provider
trace.set_tracer_provider(provider)
# Acquire a tracer
tracer = trace.get_tracer(__name__)
def my_function():
with tracer.start_as_current_span("my_function_span") as span:
span.set_attribute("event", "example")
print("Executing my_function")
nested_function()
def nested_function():
with tracer.start_as_current_span("nested_function_span"):
print("Executing nested_function")
if __name__ == "__main__":
print(f"Sending traces for service: {SERVICE_NAME} to {OTLP_ENDPOINT}")
my_function()
# It's important to shut down the tracer provider to ensure all spans are flushed
provider.shutdown()
Debug
Known issues
breakingThe direct `lightstep-tracer-python` library is officially deprecated in favor of OpenTelemetry. Existing applications using `lightstep.Tracer` directly will not receive new features or bug fixes, and users are strongly advised to migrate.fixMigrate your instrumentation to use the OpenTelemetry Python SDK and its exporters for Lightstep/Cloud Observability. Refer to official Lightstep/OpenTelemetry documentation.
affects: <= 4.4.8
deprecatedThe `lightstep` PyPI package, which provides the `lightstep-tracer-python` OpenTracing implementation, is deprecated. Lightstep (now ServiceNow Cloud Observability) has fully embraced OpenTelemetry.fixUse `pip install opentelemetry-distro opentelemetry-exporter-otlp` and instrument your applications with OpenTelemetry APIs and SDKs. Configure OTLP exporter to send data to Lightstep.
affects: All versions
gotchaInstalling multiple versions of OpenTelemetry packages, or older Lightstep tracers alongside OpenTelemetry, can cause traces not to be created or propagated correctly due to conflicts.fixEnsure only a single, consistent set of OpenTelemetry packages is installed. Check your `pip freeze` output and dependency trees. Remove any old `lightstep` or `opentracing` libraries if you're fully migrating to OpenTelemetry.
affects: All versions
gotchaWhen using `opentelemetry-bootstrap -a install` on slim Linux distributions (e.g., CentOS), you might encounter issues due to missing `gcc` and `gcc-c++` compilers.fixInstall `gcc` and `gcc-c++` (or equivalent build-essential packages) on your system before running the installation command.
affects: All OpenTelemetry-related versions
Upgrade
Version history
4.4.8latest on PyPI · released Sep 22, 2020
Audit
Dependencies
opentracingrequiredRequired by the deprecated lightstep-tracer-python library for OpenTracing API compliance.
opentelemetry-distrorequiredRecommended for OpenTelemetry-based tracing to Lightstep/Cloud Observability. Provides API, SDK, and auto-instrumentation tools.
opentelemetry-exporter-otlprequiredRequired for exporting OpenTelemetry data using OTLP (OpenTelemetry Protocol), which Lightstep/Cloud Observability supports.
protobuf==3.20.1optionalSpecifically required by `opentelemetry-launcher` for compatibility if using that (which is also deprecated, but part of a transition path).