Lumigo OpenTelemetry Distribution for Python
Project description
Lumigo OpenTelemetry Distro for Python :stars:
The Lumigo OpenTelemetry Distribution for Python is a package that provides no-code distributed tracing for containerized applications.
The Lumigo OpenTelemetry Distribution for Python is made of several upstream OpenTelemetry packages, with additional automated quality-assurance and customizations that optimize for no-code injection, meaning that you should need to update exactly zero lines of code in your application in order to make use of the Lumigo OpenTelemetry Distribution. (See the No-code instrumentation section for auto-instrumentation instructions)
Note: If you are looking for the Lumigo Python tracer for AWS Lambda functions, lumigo-tracer
is the package you should use instead.
Setup
Adding the Lumigo OpenTelemetry Distro for Python to your application is a three-step process:
- Add the Lumigo OpenTelemetry Distro for Python as dependency
- Provide configurations through environment variables
- Activate the tracer, which can also be achieved through environment variables
Add lumigo_opentelemetry as dependency
The lumigo_opentelemetry
package needs to be a dependency of your application.
In most cases, you will add lumigo_opentelemetry
as a line in requirements.txt
:
lumigo_opentelemetry
Or, you may use pip
:
pip install lumigo_opentelemetry
Environment-based configuration
Configure the LUMIGO_TRACER_TOKEN
environment variable with the token value generated for you by the Lumigo platform, under Settings --> Tracing --> Manual tracing
:
LUMIGO_TRACER_TOKEN=<token>
Replace <token>
below with the token generated for you by the Lumigo platform.
It is also strongly suggested that you set the OTEL_SERVICE_NAME
environment variable with, as value, the service name you have chosen for your application:
OTEL_SERVICE_NAME=<service name>
Replace <service name> with the desired name of the service
.
Note: While you are providing environment variables for configuration, consider also providing the one needed for no-code tracer activation :-)
Tracer activation
There are two ways to activate the lumigo_opentelemetry
package: one based on importing the package in code (manual activation), and the other via the environment (no-code activation).
The no-code activation approach is the preferred one.
No-code activation
Note: The instructions in this section are mutually exclusive with those provided in the Manual instrumentation section.
Set the following environment variable:
AUTOWRAPT_BOOTSTRAP=lumigo_opentelemetry
Manual activation
Note: The instructions in this section are mutually exclusive with those provided in the No-code activation section.
Import lumigo_opentelemetry
at the beginning of your main file:
import lumigo_opentelemetry
Configuration
OpenTelemetry configurations
The Lumigo OpenTelemetry Distro for Python is made of several upstream OpenTelemetry packages, together with additional logic and, as such, the environment varoables that work with "vanilla" OpenTelemetry work also with the Lumigo OpenTelemetry Distro for Python. Specifically supported are:
- General configurations
- Batch span processor configurations: The Lumigo OpenTelemetry Distro for Python uses a batch processor for sending data to Lumigo.
Lumigo-specific configurations
The lumigo_opentelemetry
package additionally supports the following configuration options as environment variables:
LUMIGO_TRACER_TOKEN
: [Required] Required configuration to send data to Lumigo; you will find the right value in Lumigo underSettings -> Tracing -> Manual tracing
.LUMIGO_DEBUG=TRUE
: Enables debug loggingLUMIGO_DEBUG_SPANDUMP
: path to a local file where to write a local copy of the spans that will be sent to Lumigo; this option handy for local testing but should not be used in production unless you are instructed to do so by Lumigo support.LUMIGO_SECRET_MASKING_REGEX=["regex1", "regex2"]
: Prevents Lumigo from sending keys that match the supplied regular expressions. All regular expressions are case-insensitive. By default, Lumigo applies the following regular expressions:[".*pass.*", ".*key.*", ".*secret.*", ".*credential.*", ".*passphrase.*"]
.LUMIGO_SWITCH_OFF=TRUE
: This option disables the Lumigo OpenTelemetry distro entirely; no instrumentation will be injected, no tracing data will be collected.
Supported runtimes
- cpython: 3.7.x, 3.8.x, 3.9.x, 3.10.x
Supported packages
Instrumentation | Package | Supported Versions |
---|---|---|
boto | boto3 | 1.17.22~1.24.31 |
fastapi | fastapi | 0.56.1~0.79.0 |
uvicorn | 0.11.3~0.18.2 | |
flask | flask | 2.0.0~2.1.3 |
pymongo | pymongo | 3.10.0~3.12.3 |
pymysql | pymysql | 0.9.0~0.10.1 |
1.0.0~1.0.2 |
Baseline setup
The Lumigo OpenTelemetry Distro will automatically create the following OpenTelemetry constructs provided to a TraceProvider
.
Resource attributes
SDK resource attributes
-
The attributes from the default resource:
telemetry.sdk.language
:python
telemetry.sdk.name
:opentelemetry
telemetry.sdk.version
: depends on the version of theopentelemetry-sdk
included in the dependencies
-
The
lumigo.distro.version
containing the version of the Lumigo OpenTelemetry Distro for Python as specified in the VERSION file
Process resource attributes
-
The following
process.runtime.*
attributes as specified in the Process Semantic Conventions:process.runtime.description
process.runtime.name
process.runtime.version
-
A non-standard
process.environ
resource attribute, containing a stringified representation of the process environment, with environment variables scrubbed based on theLUMIGO_SECRET_MASKING_REGEX
configuration.
Amazon ECS resource attributes
If the instrumented Python application is running on the Amazon Elastic Container Service (ECS):
cloud.provider
attribute with valueaws
cloud.platform
with valueaws_ecs
container.name
with the hostname of the ECS Task containercontainer.id
with the ID of the Docker container (based on the cgroup id)
If the ECS task uses the ECS agent v1.4.0, and has therefore access to the Task metadata endpoint version 4, the following experimental attributes as specified in the AWS ECS Resource Attributes specification:
aws.ecs.container.arn
aws.ecs.cluster.arn
aws.ecs.launchtype
aws.ecs.task.arn
aws.ecs.task.family
aws.ecs.task.revision
Span exporters
- If the
LUMIGO_TRACER_TOKEN
environment variable is set: a BatchSpanProcessor, which uses anOTLPSpanExporter
to push tracing data to Lumigo - If the
LUMIGO_DEBUG_SPANDUMP
environment variable is set: aSimpleSpanProcessor
, which uses anConsoleSpanExporter
to save to file the spans collected. Do not use this in production!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for lumigo_opentelemetry-1.0.11-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a7af1659aec7cd61504df52f36d50a18a67700a341bfc20f67363f9b06a5f333 |
|
MD5 | 3d6c735c184d267099c360ccd0b21512 |
|
BLAKE2b-256 | 35f6f6331a9ff9c7393eb2d920c9143023a3735e753568b874f0ff0465436186 |