Flask OpenTelemetry Instrumentation

This document contains instructions on how to set up OpenTelemetry instrumentation in your Flask applications and view your application traces in SigNoz.

Requirements

Python 3.8 or newer

Send Traces to SigNoz Cloud

Based on your application environment, you can choose the setup below to send traces to SigNoz Cloud.

From VMs, there are two ways to send data to SigNoz Cloud.

Send traces directly to SigNoz Cloud
Send traces via OTel Collector binary (recommended)

Send traces directly to SigNoz Cloud

Step 1. Create a virtual environment

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

Step 2. Install the OpenTelemetry dependencies

pip install opentelemetry-distro==0.43b0
pip install opentelemetry-exporter-otlp==1.22.0

The dependencies included are briefly explained below:

opentelemetry-distro - The distro provides a mechanism to automatically configure some of the more common options for users. It helps to get started with OpenTelemetry auto-instrumentation quickly.

opentelemetry-exporter-otlp - This library provides a way to install all OTLP exporters. You will need an exporter to send the data to SigNoz.

📝 Note

💡 The opentelemetry-exporter-otlp is a convenience wrapper package to install all OTLP exporters. Currently, it installs:

opentelemetry-exporter-otlp-proto-http
opentelemetry-exporter-otlp-proto-grpc
(soon) opentelemetry-exporter-otlp-json-http

The opentelemetry-exporter-otlp-proto-grpc package installs the gRPC exporter which depends on the grpcio package. The installation of grpcio may fail on some platforms for various reasons. If you run into such issues, or you don't want to use gRPC, you can install the HTTP exporter instead by installing the opentelemetry-exporter-otlp-proto-http package. You need to set the OTEL_EXPORTER_OTLP_PROTOCOL environment variable to http/protobuf to use the HTTP exporter.

Step 3. Add automatic instrumentation

opentelemetry-bootstrap --action=install

📝 Note

Please make sure that you have installed all the dependencies of your application before running the above command. The command will not install instrumentation for the dependencies which are not installed.

Step 4. Run your application

OTEL_RESOURCE_ATTRIBUTES=service.name=<service_name> \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>" \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
opentelemetry-instrument <your_run_command>

Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key.
<service_name> is name of your service

📝 Note

Don’t run app in reloader/hot-reload mode as it breaks instrumentation. For example, if you use export Flask_ENV=development, it enables the reloader mode which breaks OpenTelemetry instrumentation.

Step 5. Validate if your application is sending traces to SigNoz cloud by following the instructions here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Send traces via OTel Collector binary

Step 1. Install OTel Collector binary

OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes.

You can find instructions to install OTel Collector binary here in your VM.

Step 2. Create a virtual environment

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

Step 3. Install the OpenTelemetry dependencies

pip install opentelemetry-distro==0.43b0
pip install opentelemetry-exporter-otlp==1.22.0

The dependencies included are briefly explained below:

opentelemetry-distro - The distro provides a mechanism to automatically configure some of the more common options for users. It helps to get started with OpenTelemetry auto-instrumentation quickly.

opentelemetry-exporter-otlp - This library provides a way to install all OTLP exporters. You will need an exporter to send the data to SigNoz.

📝 Note

💡 The opentelemetry-exporter-otlp is a convenience wrapper package to install all OTLP exporters. Currently, it installs:

opentelemetry-exporter-otlp-proto-http
opentelemetry-exporter-otlp-proto-grpc
(soon) opentelemetry-exporter-otlp-json-http

Step 4. Add automatic instrumentation

opentelemetry-bootstrap --action=install

📝 Note

Step 5. To run your application and send data to collector in same VM:

OTEL_RESOURCE_ATTRIBUTES=service.name=<service_name> \
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317" \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc opentelemetry-instrument <your run command>

📝 Note

<service_name> is the name of service you want

<your_run_command> can be python3 app.py or flask run

http://localhost:4317 for gRPC exporter and http://localhost:4318 for HTTP exporter.

📝 Note

The port numbers are 4317 and 4318 for the gRPC and HTTP exporters respectively.

In case you have OtelCollector Agent in different VM, replace localhost:4317 with <IP Address of the VM>:4317.

Step 6. You can validate if your application is sending traces to SigNoz cloud by following the instructions here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Validating instrumentation by checking for traces

With your application running, you can verify that you’ve instrumented your application with OpenTelemetry correctly by confirming that tracing data is being reported to SigNoz.

To do this, you need to ensure that your application generates some data. Applications will not produce traces unless they are being interacted with, and OpenTelemetry will often buffer data before sending. So you need to interact with your application and wait for some time to see your tracing data in SigNoz.

Validate your traces in SigNoz:

Trigger an action in your app that generates a web request. Hit the endpoint a number of times to generate some data. Then, wait for some time.
In SigNoz, open the Services tab. Hit the Refresh button on the top right corner, and your application should appear in the list of Applications.
Go to the Traces tab, and apply relevant filters to see your application’s traces.

You might see other dummy applications if you’re using SigNoz for the first time. You can remove it by following the docs here.

Running applications with Gunicorn, uWSGI

For application servers which are based on pre fork model like Gunicorn, uWSGI you have to add a post_fork hook or a @postfork decorator in your configuration.

Check this documentation from OpenTelemetry on how to set it up.

Here's a working example where we have configured a gunicorn server with post_fork hook.

Troubleshooting your installation

Spans are not being reported

If spans are not being reported to SigNoz, try enabling debug exporter which writes the JSON formatted trace data to the console by setting env var OTEL_TRACES_EXPORTER=console.

OTEL_RESOURCE_ATTRIBUTES=service.name=python_app OTEL_TRACES_EXPORTER=console opentelemetry-instrument <your run command>

{
    "name": "alice",
    "context": {
        "trace_id": "0xedb7caf0c8b082a9578460a201759193",
        "span_id": "0x57cf7eee198e1fed",
        "trace_state": "[]"
    },
    "kind": "SpanKind.INTERNAL",
    "parent_id": null,
    "start_time": "2022-03-27T14:55:18.804758Z",
    "end_time": "2022-03-27T14:55:18.804805Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {},
    "events": [],
    "links": [],
    "resource": {
        "telemetry.sdk.language": "python",
        "telemetry.sdk.name": "opentelemetry",
        "telemetry.sdk.version": "1.10.0",
        "service.name": "my-service"
    }
}

Sample Flask Application

Working example where we have configured a gunicorn server with post_fork hook.
We have included a sample Flask application with README.md at Sample Flask App Github Repo.

Was this page helpful?

Try SigNoz Cloud for FREE

Instant setup, predictable pricing, and advanced features without infrastructure hassles.

Get Started - Free