Installing Custom PHP Extension on RunCloud - Excimer for Sentry Profiling

I'll be quick, because I just need to record these steps.

1. Why Excimer? What Are We Doing & Why?

• Excimer is the sampling profiler behind Sentry’s PHP profiling feature. It enables you to capture detailed performance data like CPU usage, call stacks, and slow code paths, directly from production usage. Sentry requires PHP 7.2+, and Excimer only runs on Linux or macOS—not Windows. 
• RunCloud applies a custom PHP stack that isn’t compatible with Ubuntu’s packaged modules. Hence, you must compile and install Excimer manually—and match your environment’s PHP version (e.g. php83rc). 

2. Preparation & Dependencies

Run these to ensure your build environment is ready:

sudo apt install -y build-essential pkg-config automake libtool

• build-essential: compilers and core tools
• autoconf, automake, libtool, pkg-config: necessary for building PHP extensions from source

3. Download Excimer Source Code

git clone https://github.com/wikimedia/mediawiki-php-excimer.git excimer
cd excimer

This pulls the latest version of the Excimer extension from Wikimedia’s repository.

4. Compile Against Your RunCloud PHP

Using your specific RunCloud PHP CLI tools (e.g. for PHP 8.3):

/RunCloud/Packages/php83rc/bin/phpize && \
./configure --with-php-config=/RunCloud/Packages/php83rc/bin/php-config && \
make && \
sudo make install

echo "extension=excimer.so" > /etc/php83rc/conf.d/excimer.ini

service php83rc-fpm restart

php -i | grep excimer

Explanation:

• phpize prepares the build environment.
• configure --with-php-config=... ensures the extension compiles for RunCloud’s PHP version.
• make builds the .so file.
• sudo make install places the compiled extension in your PHP module directory.  

5. Enable the Excimer Extension

Create an .ini file to automatically load Excimer in FPM:

echo "extension=excimer.so" | sudo tee /etc/php83rc/conf.d/excimer.ini

Then restart PHP-FPM:

sudo service php83rc-fpm restart

6. Verify Activation

php -i | grep excimer

You should see version and configuration info. If not, check your .ini path and restart.

7. Bonus: Full Script Template

#!/usr/bin/env bash
set -e

sudo apt update
sudo apt install -y build-essential autoconf automake libtool pkg-config
git clone https://github.com/wikimedia/mediawiki-php-excimer.git excimer
cd excimer

PHP_VERSION=83
PHPIZE="/RunCloud/Packages/php${PHP_VERSION}rc/bin/phpize"
PHP_CONFIG="/RunCloud/Packages/php${PHP_VERSION}rc/bin/php-config"

$PHPIZE
./configure --with-php-config=$PHP_CONFIG
make
sudo make install

echo "extension=excimer.so" | sudo tee /etc/php${PHP_VERSION}rc/conf.d/excimer.ini
sudo service php${PHP_VERSION}rc-fpm restart

php -i | grep excimer

Remember to add these constant to your .env to start profiling your application into Sentry.

SENTRY_LARAVEL_DSN=https://xxxxx@sentry-domain/22
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_PROFILES_SAMPLE_RATE=1.0

Thats all for now.

See you again, later.