Naming Transactions

From a Monitoring perspective, a transaction is a group of server-side requests which have been traced by Blackfire, and for which a name has been defined, according to the supported frameworks.

It may correspond to a controller, a specific action, or a view, depending on whatever is relevant to your application or framework.

Blackfire Monitoring supports all kinds of PHP and Python applications, and provides extended support for various frameworks, such as Symfony, Laravel, Magento, Django, or FastAPI.

The transactions list is designed to ease focusing on code parts that have the highest resource consumption impact.

When Blackfire is not able to automatically name transactions, it groups them separately as Unnamed transactions.

You may inspect the traces within it to name the transactions manually.

We recommend naming unnamed transaction programmatically using the snippet below:

PHP Application

1
2
// As of Blackfire PHP Probe 1.44.0
\BlackfireProbe::setTransactionName('user_model::show');

Python Application

1
2
3
4
from blackfire import apm

# As of Blackfire Python Probe 1.5.5
apm.set_transaction_name('user_model.show');

You may also configure custom transactions from the user interface (UI).

Manually named transactions using the UI cannot be profiled automatically nor be targeted by the profile next request CTA.

Transactions need to be named programmatically for automatic profiling and Profile next request to work.

Click on the Configure Custom Transaction Names button from your monitoring settings or from the Unnamed transaction view to configure custom transactions names:

A panel appears, allowing you to configure the transaction names based on the URI pattern. The pattern can be defined either using a regular expression or using a glob pattern.

For each pattern, you need to define a single name that is to be assigned to the corresponding transaction.

To help you identify the URIs that need to be recognized as transactions, a list of the latest URLs, which did not correspond to any transaction, is provided.

Monitoring for CLI commands and consumers needs to be manually triggered:

PHP Application

1
2
3
4
5
6
// As of Blackfire PHP Probe 1.78.0
\BlackfireProbe::startTransaction('my_transaction_name');

// ...

\BlackfireProbe::stopTransaction();

Python Application

1
2
3
4
5
6
7
8
9
10
11
from blackfire import apm

# As of Blackfire Python Probe 1.6.1
apm.start_transaction();

# CLI transactions should be manually named
apm.set_transaction_name('user_model.show');

# ...

apm.stop_transaction();