Explore, integrate, and innovate: creating custom integrations with Blackfire PHP and Python SDKs

Developers are continually on the lookout for innovative methods to enhance their applications’ performance and ensure long-term success. As applications become more complex, they may rely on cutting-edge technologies or intricate scaffolding, necessitating custom tools to effectively monitor resource consumption. 

Here’s to the makers

Blackfire SDKs are designed to address these challenges, providing a comprehensive solution that empowers developers to create tailored solutions for their specific needs. By building custom integrations with Blackfire SDKs, developers can confidently fulfill their observability needs and control resource consumption even for the most complex environments.

Let’s explore in this post how to get started with Blackfire PHP and Python SDKs. A special shoutout to the makers and the explorers—let’s build something new together today.

Getting started

The PHP SDK can be added with composer and works from PHP 5.3+:

composer require blackfire/php-sdk

The main entry point of the PHP SDK is the Blackfire\Client class:

$blackfire = new \Blackfire\Client();

The Python SDK is available with the Blackfire Python Package. The main entry point of the SDK is the blackfire module:

from blackfire import probe

The Blackfire Probes internal class and configuration can be found in the PHP and Python documentation.

Profiling with the SDKs

Any parts of the code can be profiled with the SDKs. This allows precise control of what should be profiled and what should not. This can also be interesting when locating memory leaks crashing the entire thread.

In PHP:

$blackfire = new \Blackfire\Client();

$probe = $blackfire->createProbe();

// some PHP code you want to profile
$profile = $blackfire->endProbe($probe);

In Python:

from blackfire import probe

probe.initialize()
probe.enable()
# some Python code you want to profile
probe.end()

The createProbe and probe.initialize methods will reset possible existing Probe instances that an existing profiling request could have instantiated. In such cases, the already collected data are dropped. New data is gathered as soon as the probe gets enabled again.

The programmatically created Blackfire Probe instance can be manually configured to improve your control of the instrumentation even more .  The PHP createProbe() method takes an optional Blackfire\Profile\Configuration object when the Python probe.initialize method takes many optional parameters that can be overridden.

Controlling Monitoring

Monitoring can also be controlled programmatically. If all HTTP requests are monitored out-of-the-box, CLI commands monitoring has to be manually configured. You decide whether you want to monitor long-running processes or each job granularly.

Controlling Monitoring requires indicating when monitoring should be started, when it ends, and giving that trace a name. This gives the following snippets for PHP:

\BlackfireProbe::startTransaction('my_transaction_name');

// monitored code

\BlackfireProbe::stopTransaction();

And Python:

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('my_transaction_name');

# ...

apm.stop_transaction();

This is also how you programmatically name transactions that were not automatically identified. When Blackfire cannot automatically name transactions, it groups them separately as Unnamed transactions. 

We’ve only scratched the surface of what the PHP and Python SDKs offer in this post. You have ways to go even deeper when it comes to controlling the profiles, getting access to their results, and even controlling Blackfire Builds! The possibilities are endless, and we’re excited to see what incredible projects and ideas you’ll bring to life using our SDKs. 

Let’s continue this conversation on Discord, Twitter, and Reddit to share your experiences, discuss your projects, and exchange ideas with us and fellow Blackfire users. Together, we’ll continue to push the boundaries of observability.

So, what will you build next?

Happy Performance Programmatic Optimization!