El requisito mínimo de versión de PHP para la última versión de dd-trace-php es PHP 7. Si estás utilizando PHP 5, puedes seguir utilizando el rastreador PHP hasta la versión 0.99. PHP 5 es EOL a partir de la versión 1.0 de PHP biblioteca.
Para consultar la lista completa de compatibilidades de versiones PHP y de marcos de trabajo Datadog (incluyendo las versiones heredadas y de mantenimiento), consulta la página de requisitos de compatibilidad.
Nota: Windows sólo es compatible con APM. No utilices las marcas --enable-appsec y --enable-profiling cuando rastrees aplicaciones PHP en Windows.
Este comando instala la extensión a todos los binarios PHP que se encuentran en el host o el contenedor. Si --PHP-bin se omite, el instalador ejecuta el modo interactivo y pide al usuario que seleccione los binarios para la instalación. El valor de --PHP-bin puede ser una ruta a un binario específico en caso de que dd-rastrear-PHP sólo deba instalarse en dichos binarios.
Reinicia PHP (PHP-FPM o SAPI de Apache) y visita un endpoint de tu aplicación, habilitado para el rastreo. Para ver las trazas generadas, ve a la página de trazas APM.
Cuando no especificas --enable-appsec, la extensión AppSec se carga poco después del inicio y no está activada por defecto. Se cortocircuita inmediatamente, causando una sobrecarga de rendimiento insignificante.
Nota:
Pueden pasar unos minutos hasta que aparezcan trazas en la interfaz de usuario. Si las trazas siguen sin aparecer después de unos minutos, crea una página phpinfo() desde la máquina host y desplázate hacia abajo hasta `ddtrace`. En esta sección aparecen los checks de diagnóstico fallidos para ayudarte a identificar cualquier problema.
Apache ZTS:
Si el binario CLI PHP se ha creado como NTS (non thread-safe), mientras que Apache utiliza una versión ZTS (Zend thread-safe) de PHP, necesitas cambiar manualmente la carga de extensión del binario ZTS. Ejecuta /path/to/php-zts --ini para ver dónde se encuentra el archivo .ini de Datadog, luego añade el sufijo -zts del nombre del archivo. Por ejemplo, de extension=ddtrace-20210902.so a extension=ddtrace-20210902-zts.so.
SELinux:
Si las políticas SELinux de httpd están configuradas en el host, la funcionalidad del rastreador puede estar limitada, a menos que la escritura y la ejecución de archivos temporales esté explícitamente permitida en la configuración de SELinux:
El rastreo se activa automáticamente por defecto. Una vez instalada la extensión, ddtrace rastrea tu aplicación y envía trazas al Agent.
Datadog es compatible con todos los marcos de trabajo web listos para utilizar. La instrumentación automática funciona modificando el tiempo de ejecución de PHP para envolver ciertas funciones y métodos para rastrearlas. El rastreador PHP admite la instrumentación automática para varias bibliotecas.
Capturas de instrumentación automática:
Tiempo de ejecución del método
Datos de rastreo pertinentes, como códigos de respuesta URL y de estado para solicitudes web o consultas SQL para el acceso a bases de datos.
Excepciones no controladas, incluyendo trazas de stacks tecnológicos, si están disponibles
Recuento total de trazas (por ejemplo, solicitudes web) que circulan por el sistema
Configuración
Si es necesario, configura la biblioteca de rastreo para enviar datos de telemetría del rendimiento de la aplicación, según tus necesidades, incluyendo la configuración del etiquetado unificado de servicios. Para obtener más detalles, consulta la configuración de bibliotecas.
Rastreo de scripts de CLI de corta y larga ejecución
Se requieren pasos adicionales para instrumentar scripts de CLI. Para obtener más información, consulta Rastreo de scripts de CLI PHP.
Una vez finalizada la instalación, reinicia PHP (PHP-FPM o SAPI de Apache).
Nota: Si estás utilizando caché de segundo nivel en OPcache configurando el parámetro opcache.file_cache, elimina la carpeta de caché.
Eliminación
Para eliminar el rastreador PHP:
Para php-fpm, detén el servicio php-fpm, si no, detén el servidor web Apache.
Desvincula los archivos 98-ddtrace.ini y 99-ddtrace-custom.ini de tu carpeta de configuración PHP.
Para php-fpm, reinicia el servicio php-fpm, si no, reinicia el servidor web Apache.
Nota: Si estás utilizando caché de segundo nivel en OPcache configurando el parámetro opcache.file_cache, elimina la carpeta de caché.
Solucionar problemas de fallos de una aplicación
En el caso inusual de un fallo de la aplicación causado por el rastreador PHP, normalmente debido a un fallo de segmentación, lo mejor es lograr un volcado de núcleo o una traza Valgrind y ponerse en contacto con el servicio de asistencia de Datadog.
Instalación de símbolos de depuración
Para que los volcados de núcleo sean legibles, los símbolos de depuración de los binarios PHP deben estar instalados en el sistema que ejecuta PHP.
Para comprobar si están instalados los símbolos de depuración para PHP o PHP-FPM, utiliza gdb.
Instala gdb:
apt|yum install -y gdb
Ejecuta gdb con el binario de interés. Por ejemplo, para PHP-FPM:
gdb php-fpm
Si el resultado de gdb contiene una línea similar al texto siguiente, entonces los símbolos de depuración ya están instalados.
...
Reading symbols from php-fpm...Reading symbols from /usr/lib/debug/path/to/some/file.debug...done.
...
Si el resultado de gdb contiene una línea similar al texto siguiente, entonces los símbolos de depuración deben instalarse.
...
Reading symbols from php-fpm...(no debugging symbols found)...done.
...
CentOS
Instala el paquete yum-utils que proporciona el programa debuginfo-install:
yum install -y yum-utils
Busca el nombre de paquete de tus binarios PHP. Puede variar dependiendo del método de instalación de PHP:
yum list installed | grep php
Instala los símbolos de depuración. Por ejemplo, para el paquete php-fpm :
debuginfo-install -y php-fpm
Nota: Si el repositorio que proporciona los binarios PHP no está habilitado por defecto, puede habilitarse al ejecutar el comando debuginfo-install. Por ejemplo:
# ... dejar aquí todos los paquetes preexistentes
# añadir un `deb` deb http://deb.Debian.org/Debian-debug/ $RELEASE-debug main
# Por ejemplo para buster
debhttp://deb.Debian.org/Debian-debug/buster-debugmain
Actualiza apt:
apt update
Prueba primero nombres canónicos de paquetes para los símbolos de depuración. Por ejemplo, si el nombre del paquete es php7.2-fpm, intenta:
apt install -y php7.2-fpm-dbgsym
# si lo anterior no funciona
apt install -y php7.2-fpm-dbg
Si no encuentras símbolos de depuración, utiliza la herramienta find-dbgsym-packages. Instala el binario:
apt install -y debian-goodies
Intenta encontrar símbolos de depuración desde la ruta completa al binario o desde el identificador de procesos de un proceso en ejecución:
find-dbgsym-packages /usr/sbin/php-fpm7.2
Instala el nombre de paquete resultante, si lo encuentras:
Si PHP se ha instalado desde ppa:ondrej/php, edita el archivo fuente apt /etc/apt/sources.list.d/ondrej-*.list añadiendo el componente main/debug.
Antes:
deb http://ppa.launchpad.net/ondrej/php/ubuntu <version> main
Después:
deb http://ppa.launchpad.net/ondrej/php/ubuntu <version> main main/debug
Actualiza e instale los símbolos de depuración. Por ejemplo, para PHP-FPM 7.2:
apt update
apt install -y php7.2-fpm-dbgsym
PHP instalado desde un paquete diferente
Busca el nombre de paquete de tus binarios PHP. Puede variar dependiendo del método de instalación de PHP:
apt list --installed | grep php
Nota: En algunos casos php-fpm puede ser un metapaquete que hace referencia al paquete real, por ejemplo php7.2-fpm en el caso de PHP-FPM 7.2. En este caso, el nombre de paquete es este último.
Prueba primero nombres canónicos de paquetes para los símbolos de depuración. Por ejemplo, si el nombre del paquete es php7.2-fpm, intenta:
apt install -y php7.2-fpm-dbgsym
# si lo anterior no funciona
apt install -y php7.2-fpm-dbg
Si los paquetes -dbg y -dbgsym no se pueden encontrar, habilita los respositorios ddebs. Para obtener información detallada sobre cómo instalar símbolos de depuración desde los ddebs, consulta la documentación de Ubuntu.
Por ejemplo, para Ubuntu v18.04 y posterior, habilita el repositorio ddebs:
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs) main restricted universe multiverse" | tee -a /etc/apt/sources.list.d/ddebs.list
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs)-updates main restricted universe multiverse" | tee -a /etc/apt/sources.list.d/ddebs.list
Obtener un volcado de núcleo para aplicaciones PHP puede ser complicado, especialmente en PHP-FPM. Aquí tienes algunos consejos para ayudarte a obtener un volcado de núcleo:
Determina si PHP-FPM ha generado un volcado de núcleo consultando el log de errores de aplicación:
Busca (SIGSEGV - core dumped), ya que un mensaje como este significa que el núcelo ha sido volcado: WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV - core dumped) after <duration> seconds from start.
Busca , ya que un mensaje como éste indica que el núcleo no ha sido volcado: WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV) after <duration> seconds from start.
Localiza el volcado de núcleo ejecutando cat /proc/sys/kernel/core_pattern. El valor por defecto suele ser core, lo que significa que se generará un archivo llamado core en la carpeta raíz de la web.
Si no se ha generado ningún volcado de núcleo, comprueba las siguientes configuraciones y cámbielas, si es necesario:
Si /proc/sys/kernel/core_pattern contiene una ruta que incluye directorios anidados, asegúrate de que existe la ruta completa del directorio.
Si el usuario que ejecuta el pool de trabajadores PHP-FPM no es root (un nombre de usuario común es www-data), proporciónale permisos de escritura en el directorio de volcados de núcleo.
Asegúrate de que el valor de /proc/sys/fs/suid_dumpable no es 0. Configúralo en 1 o 2, a menos que ejecutes pool de trabajadores PHP-FPM como root. Consulta tus opciones con el administrador del sistema.
Asegúrate de que tienes un rlimit_core adecuado en la sección de configuración del pool PHP-FPM. Puedes configurarlo como ilimitado: rlimit_core = unlimited.
Asegúrate de que dispones de un conjunto ulimit en tu sistema. Puedes configurarlo como ilimitado: ulimit -c unlimited.
Si tu aplicación se ejecuta en un contenedor Docker, los cambios en /proc/sys/* deben realizarse en la máquina host. Ponte en contacto con el administrador del sistema para conocer las opciones disponibles. Si puedes, intenta recrear la incidencia en tus entornos de test o de staging.
Obtener un volcado de núcleo desde dentro de un contenedor Docker
Utiliza la siguiente información para ayudarte a obtener un volcado de núcleo en un contenedor Docker:
El contenedor Docker necesita ejecutarse como contenedor privilegiado y el valor ulimit para los archivos del núcleo necesita ser ajustado a su máximo, como se muestra en los siguientes ejemplos.
Si utilizas el comando docker run, añade los argumentos --privileged y --ulimit core=99999999999.
Si utilizas docker compose, añade los siguiente al archivo docker-compose.yml:
privileged:trueulimits:core:99999999999
Cuando ejecutes el contenedor (y antes de iniciar la aplicación PHP), debes ejecutar los siguientes comandos:
Para obtener más detalles sobre el fallo, ejecuta la aplicación con Valgrind. A diferencia de los volcados de núcleo, este método siempre opera en un contenedor sin privilegios.
Nota: Una aplicación que se ejecuta a través de Valgrind es órdenes de magnitud más lenta que cuando se ejecuta de forma nativa. Se recomienda este método para entornos que no son de producción.
Instala Valgrind con tu gestor de paquetes. Ejecuta la aplicación con Valgrind lo suficiente para generar unas cuantas solicitudes.
La traza de Valgrind resultante se imprime por defecto en el error estándar. Para imprimir en un destino diferente, consulta la documentación oficial. El resultado esperado es similar al ejemplo siguiente para un proceso PHP-FPM:
Algunos problemas son causados por factores externos, por lo que puede ser valioso disponer de un strace.
Nota: Una aplicación que se ejecuta a través de straces es órdenes de magnitud más lenta que cuando se ejecuta de forma nativa. Se recomienda este método para entornos que no son de producción.
Instala el strace con tu gestor de paquetes. Cuando generes un strace para enviarlo al servicio de asistencia de Datadog, asegúrate de utilizar la opción -f para seguir a procesos secundarios.
