OpenTelemetry guide for Django and PostgreSQL/MySQL

In this article, you will learn how to use OpenTelemetry with Uptrace to monitor Django and PostgreSQL/MySQL performance.


What is tracing?

Distributed tracingopen in new window allows you to see how a request progresses through different services and systems, timings of each operation, any logs and errors as they occur.

In a distributed environment, tracing also helps you understand relationships and interactions between microservices. Distributed tracing gives an insight into how a particular microservice is performing and how that service affects other microservices.

Using tracing, you can break down requests into spansopen in new window. Span is an operation (unit of work) your app performs handling a request, for example, a database query or a network call.

Trace is a tree of spans that shows the path that a request makes through an app. Root span is the first span in a trace.

To learn more about tracing, see Distributed Tracing using OpenTelemetryopen in new window.

What is OpenTelemetry?

OpenTelemetry is a vendor-neutral standard on how to collect telemetry data for applications and their supporting infrastructures. OpenTelemetry was created via the merger of OpenCensus and OpenTracing projects.

OpenTelemetry aims to standardize how you collect and send telemetry data to backend platforms: distributed tracingopen in new window, OpenTelemetry metricsopen in new window, and logsopen in new window.

Creating spans

To measure performance of database queries or HTTP requests, you can create a span using OpenTelemetry Python API:

from opentelemetry import trace

tracer = trace.get_tracer("app_or_package_name", "1.0.0")

def some_func(**kwargs):
    with tracer.start_as_current_span("some-func") as span:
        // the code you are measuring

To record contextual information, you can annotate spans with attributesopen in new window. For example, an HTTP endpoint may have such attributes as http.method = GET and http.route = /projects/:id.

# To avoid expensive computations, check that span is recording
# before setting any attributes.
if span.is_recording():
    span.set_attribute("http.method", "GET")
    span.set_attribute("http.route", "/projects/:id")

You can also record exceptions and set the span status code to indicate an error:

except ValueError as exc:
    # Record the exception and update the span status.
    span.set_status(trace.Status(trace.StatusCode.ERROR, str(exc)))

See OpenTelemetry Python tracingopen in new window for details.

What is Uptrace?

Uptrace is an open source APMopen in new window for OpenTelemetry that helps developers pinpoint failures and find performance bottlenecks. Uptrace can process billions of spans on a single server and allows to monitor your software at 10x lower cost.

You can get startedopen in new window with Uptrace by downloading a DEB/RPM package or a pre-compiled Go binary.

Example application

In this tutorial, you will be instrumenting a toy appopen in new window that uses Django and PostgreSQL database client. You can retrieve the source code with the following command:

git clone
cd example/django

The app comes with some dependencies that you can install with:

pip install -r requirements.txt

Then you can run migrations to initialize the database:

./ migrate

Configuring OpenTelemetry

Uptrace provides OpenTelemetry Python distro that configures OpenTelemetry SDK for you. To install the distro:

pip install uptrace

Then you need to initialize OpenTelemetry whenever the app is started, for example, in


import uptrace

def main():
        # Copy DSN here or use UPTRACE_DSN env var.
        # dsn="",

    # other code

See Uptrace Pythonopen in new window documentation for details.

Instrumenting Django

To instrument Django, you need a corresponding OpenTelemetry Django instrumentationopen in new window:

pip install opentelemetry-instrumentation-django

Django instrumentation uses DJANGO_SETTINGS_MODULE env variable to find settings file. Django defines that variable in file so you should instrument Django app from that file:


from opentelemetry.instrumentation.django import DjangoInstrumentor

def main():
    # DjangoInstrumentor uses DJANGO_SETTINGS_MODULE to instrument the project.
    # Make sure the var is available before you call the DjangoInstrumentor.
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")


Running the example

You can start Uptrace with a single command using Docker exampleopen in new window:

docker-compose up -d

And then start the appopen in new window passing Uptrace DSN as an env variable:

export UPTRACE_DSN=http://project2_secret_token@localhost:14317/2
./ runserver

The app should be serving requests on http://localhost:8000 and should render a link to Uptrace UI. After opening the link, you should see this:

Django OpenTelemetry

Instrumenting PostgreSQL/MySQL

If you want to use PostgreSQL/MySQL Django engine instead of SQLite, see OpenTelemetry Djangoopen in new window.

What's next?

Next, you can learn about OpenTelemetry Python APIopen in new window to create your own instrumentations or browse existing instrumentationsopen in new window provided by the community.

Last Updated: