documentation updates (#100)

document that observing internal functions is available from 8.2
instructions on build+debug in container with gdbserver

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

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`;
 

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" \