Python OpenTelemetry Instrumentation

This tutorial demonstrates how to instrument your Python applications to capture OpenTelemetry traces and send them to Coralogix.

OpenTelemetry-Python automatic instrumentation is the most efficient method for adding instrumentation to Python applications. Requiring minimal modifications to the code, it uses a Python agent that can be attached to any Python application, then injects bytecode to capture telemetry from a variety of popular libraries and frameworks.

Prerequisites

1. Sign up for a Coralogix account. Set up your account on the Coralogix domain corresponding to the region where your data is stored.

2. Download Python v3.9.0.

3. Install pip. Use pip to install packages from the Python Package Index and other indexes.

Instrumentation

Step 1. Package Installation

To begin instrumentation and export telemetry data, run the following commands to install the appropriate packages.

pip3 install opentelemetry-distro
pip3 install opentelemetry-instrumentation
pip3 install -Iv protobuf==4.21.12
pip3 install opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

• The opentelemetry-distro package installs the API, SDK, and the opentelemetry-bootstrap and opentelemetry-instrument tools.
• The opentelemetry-bootstrap -a install command reads through the list of packages installed in your active site-packages folder and installs the corresponding instrumentation libraries for these packages if applicable. For example, if you have already installed the flask package, running opentelemetry-bootstrap -a install will install opentelemetry-instrumentation-flask for you.
• Manual installation of instrumented packages is also possible, but requires the user to locate and install the corresponding instrumented versions of the libraries used in the code, such as opentelemetry-instrumentation-flask for Flask.

STEP 2. Configuration

Once the packages have been installed, configure the instrumentation.

export OTEL_RESOURCE_ATTRIBUTES=service.name=<ServiceName>,application.name=<CXApplicationName>,api.name=<CXSubsystemName>,cx.application.name=<CXApplicationName>,cx.subsystem.name=<CXSubsystemName>
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20<CXPrivateKey>"
export OTEL_EXPORTER_OTLP_ENDPOINT="otel-traces.<domain>:443"
export OTEL_TRACES_EXPORTER="otlp_proto_grpc"
opentelemetry-instrument python <yourapplication.py>

Configure the agent by inputting the following environment variables:

• OTEL_EXPORTER_OTLP_ENDPOINT: Input the Coralogix domain associated with your account.
• OTEL_RESOURCE_ATTRIBUTES: Input your ServiceName.
• TEL_RESOURCE_ATTRIBUTES: Input your Coralogix private key, application, and subsystem names. You will need to specify 4 RESOURCE_ATTRIBUTES for application and subsystem:
  • application.name=<CXApplicationName>
  • api.name=<CXSubSystemName>
  • cx.application.name=<CXApplicationName>
  • cx.subsystem.name=<CXSubSystemName>

Note! OTEL_EXPORTER_OTLP_TRACES_HEADERS requires a URL-encoded format. Use %20 as space between Bearer and your CXPrivateKey. For the full range of configuration options, see Agent Configuration.

Dashboard

Confirm that your traces are being sent to Coralogix.

In your Coralogix dashboard, click Explore > Tracing. You should now see the traces generated by your application.

Demo

Use a demo to validate your instrumentation. The following demo serves as a simple example of using the OpenTelemetry library to instrument a Flask web application.

STEP 1. Create the environment.

mkdir otel_python
cd otel_python

python3 -m venv .
source ./bin/activate
touch jumping.py

STEP 2. Install flask and requests .

pip install flask
pip install requests

STEP 3. Create your jumping.py python script using vi .

# These are the necessary import declarations
from opentelemetry import trace
from flask import Flask, request
from random import randint

# Create a tracer to start and end spans
tracer = trace.get_tracer_provider().get_tracer(__name__)

# Create a Flask app
app = Flask(__name__)

# Define a route for the app
@app.route("/jumpononeleg")
def jump_now():
    # When this route is accessed, call the do_jump function and return the result as a string
    return str(do_jump())

# Start a new span for the do_jump function
@tracer.start_as_current_span("do_jump")
def do_jump():
    # Generate a random number between 1 and 6
    res = randint(1, 6)
    
    # Get the current span and set attributes on it
    current_span = trace.get_current_span()
    current_span.set_attribute("jump.value", res)
    current_span.set_attribute("operation.name", "Jumping on one leg is fun!")
    current_span.set_attribute("operation.skip", [1, 2, 3])
    
    # Return the random number as the result of the function
    return res

if __name__ == "__main__":
    # Run the Flask app on port 8075 with debug mode enabled
    app.run(port=8075, debug=True, use_reloader=False)

• The tracer variable is used to start a new tracing span, which will be used to capture information about the do_jump() function.
• The @app.route("/jumpononeleg") decorator is used to define a route for the web application, and the jump_now() function is called when this route is accessed. This function simply calls the do_jump() function and returns the result as a string.
• The @tracer.start_as_current_span("do_jump") decorator is used to start a new span for the do_jump() function, which is used to capture information about the function’s execution. Inside the function, the current_span variable is used to set attributes on the span, such as the “jump.value” and “operation.name” attributes. The randint(1, 6) function is used to generate a random number between 1 and 6, which is returned as the result of the function.
• The app.run() function is called to start the Flask web application, with the port set to 8075 and debug mode enabled. The use_reloader=False option is used to prevent the server from restarting every time the code is changed.

Step 4. Run the instrumentation.

Run the instrumentation by following the instructions above.

Open up a new terminal window and run the following:

curl <http://localhost:8075/jumpononeleg>

Step 5. View your traces.

In your Coralogix dashboard, click Explore > Tracing. You should now see the traces generated by your demo application.

Support

Need help?

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to reach out to us via our in-app chat or by sending us an email at [email protected].