OCI8 и динамическая трассировка DTrace

OCI8 2.0 содержит статические зонды DTrace, которые можно использовать в операционных системах, поддерживающих DTrace. Более подробно взаимоотношения PHP и DTrace описаны в разделе Динамическая трассировка DTrace.

Установка OCI8 с поддержкой DTrace

для включения поддержки DTrace в PHP OCI8, соберите OCI8 как разделяемое расширение после установки переменной окружения PHP_DTRACE.

$ export PHP_DTRACE=yes
$ pecl install oci8

Отредактируйте php.ini задав extension_dir равным директории, в которой создался oci8.so и, также, разрешите расширение следующим образом:

extension=oci8.so

Если вы установили PHP OCI8 из PECL с использованием phpize и configure (вместо pecl), вам все еще будет необходимо установить PHP_DTRACE=yes. Это потому, что опция --enable-dtrace будет проигнорирована ограниченным скриптом configure модуля PECL.

Более подробно об установке PECL модулей читайте в разделе Установка расширений PECL.

Статические зонды DTrace в PHP OCI8

Следующие статические зонды доступны в PHP OCI8
Имя зонда Описание зонда Аргументы зонда
oci8-connect-entry Инициируется oci_connect(), oci_pconnect() и oci_new_connect(). Срабатывает до того, как соединение было установлено. char *username, char *dbname, char *charset, long session_mode, int persistent, int exclusive
oci8-connect-return Срабатывает после установки соединения. void *connection
oci8-check-connection Срабатывает, если ошибка Oracleможет привести к порче соединения. void *connection, char *client_id, int is_open, long errcode, unsigned long server_status
oci8-sqltext Срабатывает при запуске oci_parse(). void *connection, char *client_id, void *statement, char *sql
oci8-connection-close Срабатывает, когда соединение окончательно уничтожено. void *connection
oci8-error Срабатывает, если произошла ошибка Oracle. int status, long errcode
oci8-execute-mode Срабатывает при oci_execute() для выявления режима запуска. void *connection, char *client_id, void *statement, unsigned int mode

Эти зонды полезны при отладке скриптов OCI8.

Параметры connection и statement являются указателями на внутренние структуры, используемые для отслеживания соединений и запущенных запросов.

Параметр client_id устанавливается функцией oci_set_client_identifier().

Ядро PHP также содержит статические зонды. Смотрите раздел Статические зонды DTrace в ядре PHP.

Внутренние отладочные зонды DTrace в OCI8
Имя зонда
oci8-connect-expiry
oci8-connect-lookup
oci8-connect-p-dtor-close
oci8-connect-p-dtor-release
oci8-connect-type
oci8-sesspool-create
oci8-sesspool-stats
oci8-sesspool-type

Эти зонды полезны для разработчиков расширения OCI8. Для более детальной информации изуйчайте исходные коды OCI8.

Получение списка статиченских зондов DTrace в PHP OCI8

Для получения списка доступных зондов, запустите процесс PHP и, затем, запустите:

# dtrace -l

Вывод будет примерно следующим:

   ID   PROVIDER            MODULE                          FUNCTION NAME
   [ . . . ]
   17 phpoci22116           oci8.so   php_oci_dtrace_check_connection oci8-check-connection
   18 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-entry
   19 phpoci22116           oci8.so         php_oci_persistent_helper oci8-connect-expiry
   20 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-lookup
   21 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-close
   22 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-release
   23 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-return
   24 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-type
   25 phpoci22116           oci8.so          php_oci_connection_close oci8-connection-close
   26 phpoci22116           oci8.so                     php_oci_error oci8-error
   27 phpoci22116           oci8.so         php_oci_statement_execute oci8-execute-mode
   28 phpoci22116           oci8.so              php_oci_create_spool oci8-sesspool-create
   29 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-stats
   30 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-type
   31 phpoci22116           oci8.so          php_oci_statement_create oci8-sqltext

Столбец "Provider" состоит из phpoci и идентификатора запущенного процесса PHP.

Столбец "Function" содержит имена внутренних, написанных на C, функций PHP, в которых содержатся соответствующие провайдеры (Provider).

Если процесс PHP не запущен, то никаких зондов PHP показано не будет.

Пример использования DTrace с PHP OCI8

В этом примере продемонстрированы основы скриптового языка DTrace D.

Пример #1 user_oci8_probes.d для трассировки всех статических зондов PHP OCI8 с помощью DTrace на пользовательском уровне

#!/usr/sbin/dtrace -Zs

#pragma D option quiet

php*:::oci8-connect-entry
{
    printf("%lld: PHP connect-entry\n", walltimestamp);
    printf("  credentials=\"%s@%s\"\n", arg0 ? copyinstr(arg0) : "", arg1 ? copyinstr(arg1) : "");
    printf("  charset=\"%s\"\n", arg2 ? copyinstr(arg2) : "");
    printf("  session_mode=%ld\n", (long)arg3);
    printf("  persistent=%d\n", (int)arg4);
    printf("  exclusive=%d\n", (int)arg5);
}

php*:::oci8-connect-return
{
    printf("%lld: PHP oci8-connect-return\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
}

php*:::oci8-connection-close
{
    printf("%lld: PHP oci8-connect-close\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
}

php*:::oci8-error
{
    printf("%lld: PHP oci8-error\n", walltimestamp);
    printf("  status=%d\n", (int)arg0);
    printf("  errcode=%ld\n", (long)arg1);
}

php*:::oci8-check-connection
{
    printf("%lld: PHP oci8-check-connection\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
    printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
    printf("  is_open=%d\n", arg2);
    printf("  errcode=%ld\n", (long)arg3);
    printf("  server_status=%lu\n", (unsigned long)arg4);
}

php*:::oci8-sqltext
{
    printf("%lld: PHP oci8-sqltext\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
    printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
    printf("  statement=0x%p\n", (void *)arg2);
    printf("  sql=\"%s\"\n", arg3 ? copyinstr(arg3) : "");
}

php*:::oci8-execute-mode
{
    printf("%lld: PHP oci8-execute-mode\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
    printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
    printf("  statement=0x%p\n", (void *)arg2);
    printf("  mode=0x%x\n", arg3);
}

В этом скрипте с dtrace используется опция -Z, позволяющая ему запускаться даже если никаких процессов PHP не запущено. Если не задать данную опцию, то скрипт сразу же прекратит свою работу, так как отсутствуют зонды для отслеживания.

На многопроцессорных машинах порядок зондов может быть не последовательным. Это зависит от того, на каких ядрах работают зонды и каким образом потоки мегрируют между ядрами. В такой ситуации имеет смысл ориентироваться на временные метки зондов.

Скрипт отслеживает все сообщения статических зондов PHP OCI8 уровня пользователя на протяжении работы скрипта PHP. Запускаем скрипт D:

# ./user_oci8_probes.d

Запускаем скрипт PHP или свое приложение. D-скрипт будет выводить все аргументы зондов при их срабатывании. К примеру, простой скрипт PHP, выполняющий запрос к базе данных может создавать следующие сообщения:

1381794982092854582: PHP connect-entry
  credentials="hr@localhost/pdborcl"
  charset=""
  session_mode=0
  persistent=0
  exclusive=0
1381794982183158766: PHP oci8-connect-return
  connection=0x7f4a7907bfb8
1381794982183594576: PHP oci8-sqltext
  connection=0x7f4a7907bfb8
  client_id="Chris"
  statement=0x7f4a7907c2a0
  sql="select * from employees"
1381794982183783706: PHP oci8-execute-mode
  connection=0x7f4a7907bfb8
  client_id="Chris"
  statement=0x7f4a7907c2a0
  mode=0x20
1381794982444344390: PHP oci8-connect-close
  connection=0x7f4a7907bfb8

После завершения диагностики D-скрипт можно прервать с помощью нажатия ^C.