diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 5ff4b88..a4c4d68 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -80,7 +80,7 @@ needed related to installing and configuring some dependencies. Next is to add extension to ini file as described above. -After finising all above steps, you can start debugging session. There are few debuggers that +After finishing all above steps, you can start a debugging session. There are few debuggers that can be used for debugging process, lldb, gdb or visual studio debugger on windows. To trigger auto instrumentation code you need to invoke observer api functionality. Following, very simple script can be used as reference example, created and saved as test.php @@ -146,6 +146,28 @@ tests/name_of_test.sh valgrind # will run test and display valgrind report Further reading: https://www.phpinternalsbook.com/php7/memory_management/memory_debugging.html#debugging-memory +### gdbserver + +To debug tests running in a docker container, you can use `gdbserver`: + +```shell +docker build --build-arg PHP_VERSION=8.2.11 -f docker/Dockerfile.debian . -t otel:8.2.11 +docker run --rm -it -p "2345:2345" -v $(pwd)/ext:/usr/src/myapp otel:8.2.11 bash +``` + +Then, inside the container: + +```shell +phpize +./configure +make +gdbserver :2345 php -d extension=$(pwd)/modules/opentelemetry.so /path/to/file.php +``` + +Now, gdbserver should be running and awaiting a connection. Configure your IDE to connect via +`gdb` to `127.0.0.1:2345` and start debugging, which should connect to the waiting server +and start execution. + # Packaging for PECL See https://github.com/opentelemetry-php/dev-tools#pecl-release-tool diff --git a/README.md b/README.md index 8258e42..5921eb7 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,9 @@ This is a PHP extension for OpenTelemetry, to enable auto-instrumentation. It is based on [zend_observer](https://www.datadoghq.com/blog/engineering/php-8-observability-baked-right-in/) and requires php8+ -The extension allows creating `pre` and `post` hook functions to arbitrary PHP functions and methods, which allows those methods to be wrapped with telemetry. +The extension allows creating `pre` and `post` hook functions to arbitrary PHP functions and methods, which allows those methods to be wrapped with telemetry. + +In PHP 8.2+, internal/built-in PHP functions can also be observed. ## Requirements - PHP 8+ @@ -74,9 +76,8 @@ opentelemetry.validate_hook_functions => On => On ### Invalid pre/post hooks -Invalid argument types in pre and post callbacks can cause fatal errors. Runtime checking is performed on the -hook functions to ensure they are compatible. If not, the hook will not be executed and an error will be logged -to error_log. +Invalid argument types in `pre` and `post` callbacks can cause fatal errors. Runtime checking is performed on the +hook functions to ensure they are compatible. If not, the hook will not be executed and an error will be generated. This feature can be disabled by setting the `opentelemetry.validate_hook_functions` ini value to `Off`; diff --git a/docker/Dockerfile.debian b/docker/Dockerfile.debian index 3478347..ac5e0fb 100644 --- a/docker/Dockerfile.debian +++ b/docker/Dockerfile.debian @@ -37,6 +37,7 @@ RUN apt-get update -y \ ARG PHP_VERSION ENV PHP_URL="https://www.php.net/distributions/php-${PHP_VERSION}.tar.xz" ENV CFLAGS="-ggdb3" +ENV TEST_PHP_ARGS="-q" RUN echo "$PHP_URL" \ && curl -fsSL -o php.tar.xz "$PHP_URL" \