OpenTelemetry Python: Basics, Quick Tutorial, and Best Practices

OpenTelemetry Basics and Key Concepts 

OpenTelemetry is a set of APIs, libraries, agents, and instrumentation that aim to provide an open-source and standardized framework for collecting telemetry data such as metrics, logs, and traces from cloud-native software. It enables the integration of telemetry data collection into applications written in all popular programming languages, including Python, facilitating real-time monitoring and troubleshooting. 

OpenTelemetry is a Cloud Native Computing Foundation (CNCF) project that has gained traction for its role in observability, allowing developers and operators to gain insights into their systems’ performance and behavior. Here are key concepts you should be familiar with before using OpenTelemetry in your Python apps:

Distributed tracing

Distributed tracing is a method used to track the progress of requests as they travel through distributed systems. OpenTelemetry facilitates distributed tracing by automatically injecting and propagating trace context between services. This ensures that developers and operators can monitor and troubleshoot multi-service transactions without manual configuration for each service interaction.

Logs

Logs in OpenTelemetry refer to the digital records of events that occur within an application or system. These logs are crucial for debugging and monitoring purposes, providing insights into the behavior of the application and helping identify issues or anomalies in real time. OpenTelemetry standardizes the collection and export of log data, allowing it to be easily integrated with observability platforms.

Metrics

Metrics in OpenTelemetry are numerical values that are collected over time, representing various aspects of an application’s performance and usage. Common examples include request count, error count, and response times. OpenTelemetry provides a framework for capturing, aggregating, and exporting metrics from applications. This includes support for different types of metrics, such as counters, gauges, and histograms.

What Is the OpenTelemetry Python SDK?

The OpenTelemetry Python SDK provides the necessary tools and libraries for developers to instrument their Python applications with OpenTelemetry. It is designed to capture, generate, and export telemetry data, including metrics, logs, and traces, from Python applications to analytics and monitoring tools. 

This SDK simplifies the process of integrating observability into Python applications, enabling data collection and export. Developers can use it to add context to the data being collected, enrich telemetry data with custom attributes, and configure the export of data to their chosen observability platform. 

As of the time of this writing, the OpenTelemetry Python SDK supports Python version 3.6 and higher.

Quick Tutorial: Adding OpenTelemetry to a Flask-Based Python Application

Here is a walkthrough of the process of setting up and using OpenTelemetry for Python applications. The code was adapted from the OpenTelemetry documentation.

Step 1: Setting Up a Sample Flask Application

Start by creating a new environment and directory for your project and changing into it:

mkdir python-observe
cd python-observe

Create and activate a new virtual environment:

python3 -m venv venv
source ./venv/bin/activate

Install Flask in the environment:

pip install flask

Now, create an app.py file with a sample application. OpenTelemetry provides a simple Flask application that “rolls a dice” and displays the result (get the code here).

Run the application with the following command:

flask run -p 8080

Now open the URL http://localhost:8080/rolldice in your web browser to see the application is working.

Step 2: Instrumentation

For automatic telemetry data collection, the OpenTelemetry Python SDK provides several options. This guide will use the opentelemetry-instrument agent for automatic instrumentation.

Install the OpenTelemetry distribution package, which includes the API, SDK, and instrumentation tools:

pip install opentelemetry-distro

Use the following command to automatically install the necessary instrumentation packages:

opentelemetry-bootstrap -a install

This step ensures that Flask instrumentation is installed and ready to automatically generate telemetry data.

Step 3: Running the Instrumented Application

Follow these steps to run your Flask application with OpenTelemetry instrumentation, enabling it to export telemetry data to the console:

Set the environment variable to enable logging auto-instrumentation:

export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true

Start the Flask application with OpenTelemetry instrumentation, specifying the console as the exporter for traces, metrics, and logs:

opentelemetry-instrument --traces_exporter console --metrics_exporter console --logs_exporter console --service_name dice-server flask run -p 8080

Visit http://localhost:8080/rolldice in your web browser. Reloading a few times will generate spans and metrics that are printed to the console.

Step 4: Example of Manual Instrumentation—Adding a Tracer

Automatic instrumentation captures telemetry at system boundaries, but you can add manual instrumentation to capture detailed application-level telemetry.

To link manual instrumentation with automatically generated traces, first initialize a tracer within your Flask application:

from opentelemetry import trace
tracer = trace.get_tracer("diceroller.tracer")

Use the tracer to create a new span that acts as a child of the automatically generated span:

with tracer.start_as_current_span("roll") as roll_span:
    result = str(randint(1, 6))
    roll_span.set_attribute("roll.value", result)

Now run the app again:

export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
opentelemetry-instrument --traces_exporter console --metrics_exporter console --logs_exporter console --service_name dice-server flask run -p 8080

When you send a request to the server, you’ll see two spans in the trace emitted to the console.

That’s it! You created a sample Python application and used OpenTelemetry to gather observability data from it.

Best Practices for Using OpenTelemetry in Python Applications 

Combine Manual and Auto-Instrumentation

While auto-instrumentation rapidly provides insights by automatically tracking system boundaries and common libraries, manual instrumentation allows you to dive deeper into custom application logic and specific operations. 

This hybrid approach ensures that you not only capture the essential interactions within and across services but also gain the ability to pinpoint specific areas of interest within your application’s unique workflows. By strategically inserting manual spans around critical operations, you can make observability more granular.

Use Exceptions to Identify Issues in the Code

Integrating exception tracking into your OpenTelemetry instrumentation can significantly improve your ability to diagnose and address issues within your Python applications. By capturing exceptions as events within your telemetry data, you provide a direct link to potential problems, enabling quicker identification and resolution of errors. 

This practice helps in debugging by highlighting the exact location and context of failures. It also aids in monitoring the health of your application by signaling anomalies and issues in real-time. Leveraging exceptions as part of your observability strategy ensures a proactive approach to maintaining and improving application reliability and user satisfaction.

Leverage the OpenTelemetry Collector 

For Python applications in production, employing the OpenTelemetry Collector offers a scalable and efficient method for managing telemetry data. The Collector serves as an intermediary that can receive, process, and export telemetry data to various analytics and monitoring tools without requiring direct integration into your application. 

This architecture reduces the overhead on your application, simplifies configuration management, and enhances security by decoupling data collection from data processing and storage. The Collector’s ability to aggregate and filter data from multiple sources enables a unified view across services.

Get Full Observability with OpenTelemetry and Coralogix

Data plus context are key to supercharging observability using OpenTelemetry. As Coralogix is open-source friendly, we support OpenTelemetry to get your app’s telemetry data (traces, logs, and metrics) as requests travel through its many services and other infrastructure. You can easily use OpenTelemetry’s APIs, SDKs, and tools to collect and export observability data from your environment directly to Coralogix.

Learn more about OpenTelemetry support in Coralogix