Profile Python Functions Using a Decorator
The Blackfire Probe for Python now provides a decorator, simplifying the profiling experience.
Manual vs Automatic instrumentation
There are several ways to triggers profiles for your application, and it is important to distinguish whether to opt in for manual or automatic instrumentation.
Automatic instrumentation means that the Blackfire Probe is automatically initialized when the
X-Blackfire-Query HTTP header is detected, or when the
X_BLACKFIRE_QUERY environment variable is present in the CLI context. The generated profile takes every function calls into account.
In the HTTP context, the auto-instrumentation is enabled when you trigger a profile from the browser extension, or with the
blackfire curl command. At the moment, it is only available for specific frameworks when using the
blackfire-python command (read more in the dedicated article about
In the CLI context, the auto-instrumentation is enabled when running your Python script using the
blackfire-python run command:
blackfire-python run python my_script.py
The “on-demand profiling” characteristic of the auto-instrumentation makes it production safe, as it won’t impact any user other than yourself in terms of overhead.
The manual instrumentation implies that you control what the Blackfire Probe is instrumenting. You can do this using the Python SDK, by initializing a probe yourself.
While using manual instrumentation gives you more control, it also means that you need to be careful before shipping your app into production, as you may initialize a probe (and thus generate a profile) for each request! This would mean adding an overhead for every request.
This decorator allows you to instrument the code of a function in a very minimalistic way:
from blackfire import profile @profile def foo(): import time time.sleep(1.0) foo()
In this example, the
foo() function is instrumented each time it is called. The probe initializes and creates a dedicated profile.
Be careful not to push such decorated code into production as this constitutes a manual instrumentation. As such, a probe is initialized each time the decorator is called.
Give Blackfire a try?