ajunlonglive / scout-apm-php-ext

Native Extension Component for ScoutAPM's PHP Agent

Scout APM PHP Extension

The Scout APM PHP extension allows instrumentation of internal PHP functions that can't be done in regular PHP. The scout-apm-php package detects if the scoutapm extension is loaded and will automatically send this data if available.

This extension allows instrumentation of:

• Core functions: file_get_contents, file_put_contents, fread, fwrite
• Curl functions: curl_exec
• PDO methods: PDO->exec, PDO->query, PDOStatement->execute
• Predis PHP library methods
• phpredis PHP extension methods
• Memcached PHP extension methods
• Elasticsearch PHP library methods

If you would like another function instrumented, please let us know on our issues.

The following functions are exposed when the extension is enabled:

• scoutapm_enable_instrumentation(bool $enabled): void
  • Enable or disable instrumentation by ScoutAPM at runtime. Instrumentation is disabled by default, so this must be called with $enabled to true.
• scoutapm_get_calls(): array
  • Returns a list of any instrumented function calls since scoutapm_get_calls() was last called. The list is cleared each time the function is called.
• scoutapm_list_instrumented_functions(): array
  • Returns a list of the functions the extension will instrument if called.

Installing from PECL

The Scout APM extension is available to install using PECL.

$ sudo pecl install scoutapm

You may need to add zend_extension=scoutapm.so into your php.ini to enable the extension.

Building

$ phpize
$ ./configure --enable-scoutapm
$ make test

Run tests with installed PHP (avoids skipped tests):

make && php run-tests.php -d zend_extension=$(pwd)/modules/scoutapm.so --show-diff -q

Note: whilst a CMakeLists.txt exists, this project does NOT use CMake. The CMakeLists.txt exists so this project can be worked on in CLion. See https://dev.to/jasny/developing-a-php-extension-in-clion-3oo1.

Building with specific PHP build

$ /path/to/bin/phpize
$ ./configure --with-php-config=/path/to/bin/php-config --enable-scoutapm
$ make test

Building with Docker

@todo: make docker build configurable...

docker build .
docker run -v $PWD/modules:/v <hash_from_build>

Debugging

Use gdb (e.g. in CLion) to debug. Once running, php-src has a GDB helper:

source /path/to/php-src/.gdbinit
printzv <thing>
print_ht <thing>
zbacktrace
print_cvs

Windows builds

• Read this guide to put below into context: https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2
• Read this guide to help get the environment set up: https://gist.github.com/cmb69/47b8c7fb392f5d79b245c74ac496632c
• PHP Binary tools - use https://github.com/php/php-sdk-binary-tools (not the Microsoft one as it is not maintained)
• Once the VS tools + php-sdk-binary-tools is installed, everything is done in this shell:
  • Start > Developer Command Prompt for VS 2019
  • Then cd C:\php-sdk
  • Then phpsdk-vs16-x64.bat - you should now have a prompt $
• Install PHP from https://windows.php.net/download/
  • Download, e.g. ZTS build, https://windows.php.net/downloads/releases/php-8.1.7-Win32-vs16-x64.zip
  • Extract into C:\php
• Prepare to compile the ext
  • Download "Development package" from https://windows.php.net/download/ - make sure TS/NTS depending on above compilation
    • e.g. https://windows.php.net/downloads/releases/php-devel-pack-8.1.7-nts-Win32-vs16-x64.zip
  • Extract to C:\php-sdk\php-8.1.7-devel-vs16-x64
  • Add C:\php-sdk\php-8.1.7-devel-vs16-x64 to your PATH (Start > env > Environment variables > "Path" > New)
  • restart the shell
• Compile the ext - go to the ext directory (mine was a VM, mounted in Z:\)
  • Run winbuild.bat
  • Or alternatively:
    • phpize
    • configure --enable-scoutapm --enable-debug --with-php-build="C:\php-sdk\phpdev\vs16\x64\deps" --with-prefix="C:\php\"
    • nmake
    • Edit Makefile - find CC="$(PHP_CL)" and replace with CC="cl.exe" - for some reason that variable substitution didn't work
    • Also replace -d extension= with -d zend_extension=
    • Run nmake run ARGS="-m" and check scoutapm exists in both PHP Modules and Zend modules

Release Procedure

• Open package.xml
• Copy the current release into a new changelog.release element
• Update the current release section (date/time/version/stability/notes)
• pecl package-validate to check everything looks good
• Increase/verify PHP_SCOUTAPM_VERSION version listed in zend_scoutapm.h
• Commit update to package.xml
• Rebuild from scratch (full-clean.sh, then build as above)
• make test to ensure everything passes locally
• Push the branch (optionally, make a PR to GitHub) to trigger CI to build
• Once merged, close the milestone to automatically release & generate the TGZ asset
• Go to the latest release just created
• Download the TGZ asset and upload it to pecl.php.net