Sending PHP Sentry notifications asynchronously
Introduction
This article describes how to send Sentry alerts asynchronously using the sentry-php SDK in a PHP 7.4+ environment.
(This article summarizes a solution to an issue related to sentry-php.)
For reference, Sentry’s Relay is one of the proposed solutions to address response time delays caused by synchronous alert transmission. By using Relay, alerts are not sent directly to the Sentry server but are instead forwarded through a local Relay proxy process, minimizing response time.
This article presents an alternative approach to reducing communication with the Sentry server without relying on Relay.
Pattern of Promise and Non-Blocking
Since PHP is a single-threaded language, it does not support asynchronous execution in the same way as JavaScript, which relies on an event loop and a multi-threaded runtime (such as the V8 engine in Chrome or Node.js).
Moreover, the sentry-php SDK is structurally designed to send alerts synchronously. This means that, unlike JavaScript, PHP does not natively support true asynchronous execution for Sentry logging.
In this context, “asynchronous” does not refer to true concurrency but rather a non-blocking approach using the Promise pattern and curl_multi. This technique helps to reduce latency and optimize performance by preventing Sentry API calls from blocking the main execution flow.
A traditional approach to using sentry-php typically looks like this:
<?php
// define of sentry's data source name
\Sentry\init([
'dsn' => $_ENV['DSN'],
]);
\Sentry\captureMessage('test', \Sentry\Severity::warning());
// ...additional sentry calls
// endWhen calling the \Sentry\captureMessage method, the internally defined HTTP client uses PHP's built-in cURL library to send alerts to the Sentry server.
Some parts of the
Sentry\HttpClient\HttpClient.php
<?php
namespace Sentry\HttpClient;
class HttpClient implements HttpClientInterface
{
public function sendRequest(Request $request, Options $options): Response
{
// ...
$curlHandle = curl_init();
/**
* set request headers
* set curl options
*/
// ...
$body = curl_exec($curlHandle);
curl_close($curlHandle);
return new Response($statusCode, $responseHeaders, '');
}
}When the application sends Sentry alerts at various points for logging, each alert triggers communication with the Sentry server. As a result, additional latency occurs even for API requests that are not directly related to Sentry alerts.
The actual process of sending alerts is handled by the HttpClient implementation class. Additionally, the Client allows swapping out the HttpClientInterface implementation by passing a different instance when initializing Sentry using the \Sentry\init method.
Sentry\HttpClient\HttpClientInterface.php
<?php
namespace Sentry\HttpClient;
use Sentry\Options;
interface HttpClientInterface
{
public function sendRequest(Request $request, Options $options): Response;
}The custom HttpClient implementation is as follows.
SentryAsyncClientWrapper.php
<?php
namespace Jun\PhpSentryExample;
use GuzzleHttp\Client;
use GuzzleHttp\Promise\Utils;
use GuzzleHttp\Psr7\Request as Psr7Request;
use Sentry\Client as SentryClient;
use Sentry\HttpClient\HttpClientInterface;
use Sentry\HttpClient\Request;
use Sentry\Options;
use Sentry\HttpClient\Response;
class SentryAsyncClientWrapper implements HttpClientInterface
{
private static ?self $instance = null;
private Client $client;
private array $promises = [];
private string $sdkIdentifier = SentryClient::SDK_IDENTIFIER;
private string $sdkVersion = SentryClient::SDK_VERSION;
private function __construct(Client $client)
{
$this->client = $client;
}
public static function getInstance(Client $client): self
{
if (self::$instance === null) {
self::$instance = new self($client);
}
return self::$instance;
}
public function sendRequest(Request $request, Options $options): Response
{
$dsn = $options->getDsn();
if ($dsn === null) {
throw new \RuntimeException('The DSN option must be set to use the HttpClient.');
}
$requestData = $request->getStringBody();
if ($requestData === '') {
throw new \RuntimeException('The request data is empty.');
}
$sentry_version = SentryClient::PROTOCOL_VERSION;
$sentry_client = "{$this->sdkIdentifier}/{$this->sdkVersion}";
$sentry_key = $dsn->getPublicKey();
$requestHeaders['sentry_version'] = $sentry_version;
$requestHeaders['sentry_client'] = $sentry_client;
$requestHeaders['sentry_key'] = $sentry_key;
$requestHeaders['Content-Type'] = 'application/x-sentry-envelope';
$authHeader = [
'sentry_version=' . $sentry_version,
'sentry_client=' . $sentry_client,
'sentry_key=' . $sentry_key,
];
$requestHeaders['X-Sentry-Auth'] = 'Sentry ' . implode(', ', $authHeader);
if (\extension_loaded('zlib') && $options->isHttpCompressionEnabled()) {
$requestData = gzcompress($requestData, -1, \ZLIB_ENCODING_GZIP);
$requestHeaders['Content-Encoding'] = 'gzip';
}
$this->promises[] = $this->client->sendAsync(new Psr7Request(
'POST',
$dsn->getEnvelopeApiEndpointUrl(),
$requestHeaders,
$requestData
))->then(
function ($response) {
// callback for when the request succeeds
echo 'Request succeeded: ' . $response->getBody() . PHP_EOL;
},
function ($reason) {
// callback for when the request fails
echo 'Request failed: ' . $reason . PHP_EOL;
}
);
return new Response(200, [], '');
}
public function wait(): void
{
if (!empty($this->promises)) {
Utils::settle($this->promises)->wait();
$this->promises = [];
}
}
}Since the sendRequest method of HttpClientInterface is designed to return a Response object, I have made it return an empty Response object.
return new Response(200, [], '');However, this approach may prevent certain lifecycle mechanisms of the Sentry framework, such as internal rate limiting, from functioning correctly since it always returns a 200 response. Therefore, post-processing must be handled manually within the success/failure callbacks of the then method.
$this->promises[] = $this->client->sendAsync(new Psr7Request(
'POST',
$dsn->getEnvelopeApiEndpointUrl(),
$requestHeaders,
$requestData
))->then(
function ($response) {
// callback for when the request succeeds
echo 'Request succeeded: ' . $response->getBody() . PHP_EOL;
},
function ($reason) {
// callback for when the request fails
echo 'Request failed: ' . $reason . PHP_EOL;
}
);Using GuzzleHttp\Client, you can handle promises with the sendAsync method. The aggregated requests(promises) remain in a PENDING state until wait is called, at which point the actual request execution occurs.
Calling the settle method from GuzzleHttp\Promise\Utils resolves the promises in parallel. Internally, it utilizes curl_multi, allowing network requests to be processed in a non-blocking manner.
public function wait(): void
{
if (!empty($this->promises)) {
Utils::settle($this->promises)->wait();
$this->promises = [];
}
}In other words, the SentryAsyncClientWrapper class manages Promise objects and enables asynchronous network requests using GuzzleHttp\Client.
<?php
namespace Jun\PhpSentryExample;
require_once __DIR__ . '/../vendor/autoload.php';
$dotenv = \Dotenv\Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();
$asyncClient = SentryAsyncClientWrapper::getInstance(new \GuzzleHttp\Client([
'timeout' => 1,
]));
\Sentry\init([
'dsn' => $_ENV['DSN'],
'http_client' => $asyncClient,
]);
\Sentry\captureMessage('test', \Sentry\Severity::warning());
// ...additional sentry calls
// Simulate a long running process
sleep(5);
// non-blocking multiple requests
$asyncClient->wait();If wait is called when post_system is triggered, all Sentry logs accumulated during execution will be sent in parallel after the business logic has completed.
Closing
You can check the full source code here.
If you are using the CodeIgniter4 framework, you can apply it as follows:
Events::on('pre_system', static function () {
service('sentry')->initialize(); // setting async client wrapper
});
// ...
Events::on('post_system', function () {
/**
* Get the database connections And,
* Close the database connections
*/
// ...
SentryAsyncClientWrapper::getInstance(new \GuzzleHttp\Client([
'timeout' => 1,
])->wait();
});
