From f62c3bd1c299158d711d18437a2165afa2f19463 Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Tue, 10 Oct 2023 11:24:10 +1100 Subject: [PATCH 1/2] documentation updates document that observing internal functions is available from 8.2 instructions on build+debug in container with gdbserver --- DEVELOPMENT.md | 24 +++++++++++++++++++++++- README.md | 11 ++++++----- docker/Dockerfile.debian | 1 + 3 files changed, 30 insertions(+), 6 deletions(-) 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..9c8f354 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+ @@ -28,7 +30,7 @@ If you are using the [official PHP docker images](https://hub.docker.com/_/php) From github: ```shell -install-php-extensions open-telemetry/opentelemetry-php-instrumentation@main +install-php-extensions opentelemetry-php/ext-opentelemetry@main ``` Via pecl/pickle: @@ -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" \ From fd392e6c9f3895797acd26f01f6acd551ca5beee Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Tue, 10 Oct 2023 11:29:30 +1100 Subject: [PATCH 2/2] remove line --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9c8f354..5921eb7 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ If you are using the [official PHP docker images](https://hub.docker.com/_/php) From github: ```shell -install-php-extensions opentelemetry-php/ext-opentelemetry@main +install-php-extensions open-telemetry/opentelemetry-php-instrumentation@main ``` Via pecl/pickle: