PHP 追蹤延伸

Instana 代理程式需要 PHP 追蹤延伸，才能從 PHP 環境收集追蹤資料。啟用 PHP 感應器時，會自動下載 PHP 追蹤延伸。

PHP 追蹤延伸設定
啟用 PHP 追蹤器 2.0
- 第一次配置 PHP Tracer 2.0
- 升級至 PHP 追蹤器 2.0
解除安裝 Instana PHP 追蹤延伸
自動重新啟動

PHP 追蹤延伸設定

必要的 PHP 延伸

若要執行 PHP Tracer ，您必須具有 JSON 副檔名。

下載 Instana 追蹤延伸之後，該延伸會將 zzz-instana.ini 檔案放置在 Additional ini 目錄中，或將該檔案新增至 PHP SAPI 所使用的 ini 檔案。

然後，感應器會嘗試重新啟動 PHP 環境，將追蹤延伸載入記憶體中。如需相關資訊，請參閱自動重新啟動。

此外，如果您使用 Plesk ，則需要執行 plesk bin php_handler --reread。

自訂 PHP 延伸設定

對於 zzz-instana.ini中的大部分追蹤實務， PHP 追蹤延伸隨附相同的預設值。不過，您可以調整設定，以符合特定需求，例如取樣、批次處理或區塊化。

如果追蹤延伸已載入 PHP 環境中，則 PHP 感應器不會改寫 zzz-instana.ini 。因此，雖然您可以安全地在延伸中新增額外設定，但在儲存器化設定中新增額外設定可能不方便。在這類實務範例中的良好作法是新增額外檔案 zzz-instana-extras.ini ，並使該檔案成為儲存器部署的一部分。

可用的設定如下:

instana.socket:Instana PHP 感應器的 TCP Socket 位址。 Socket 位址在安裝期間決定，預設為 tcp://127.0.0.1:16816。
instana.log_level: 要記載的層次: 0 = 關閉、1 = 錯誤、2 = 警告、3 = 參考資訊，以及 4 = 除錯。預設值為 0 (關閉)。
instana.enable_cli: 啟用或停用 CLI SAPI 的追蹤。 1 = 開啟。 0 = 關閉。預設值為 0 (關閉)。
instana.batch_threshold_us: 跨距進行批次處理的長度及距離臨界值。預設值為 10000。
instana.backtrace_limit: 控制所記錄呼叫堆疊的深度。預設或受限值為 25 個項目。
instana.span_chunk_size: 在將文字段傳送至代理程式之前，要保留在 PHP 記憶體中的文字段數。這個數字會直接影響批次處理。例如，有效停用批次處理的區塊。
instana.disable_userland_tracing: 停用非原生延伸 (例如，架構及其他 PHP 使用者程式碼) 的所有追蹤。預設值為 0 (關閉)。
instana.segfault_error_log: 擷取或避免回溯 PHP 的錯誤登入區段錯誤。預設值為 0 (關閉)。
instana.disabled_instrumentation: 要停用之檢測的位元遮罩。預設值為 0 (無)。

可用旗標

可用的旗標如下:

STREAMS 1
PHP 2
PDO 4
CURL 8
REDIS 16
MONGODB 32
MYSQL 64
MEMCACHE 128
Db2 256
OCI 512
SHELL 1024
PECL_HTTP 2048
REQUEST_HEADERS 4096
RESPONSE_HEADERS 8192
SOAP 16384
Wordpress 32768
AMQP 65536 (同時適用於 pecl-amqp 和 php-amqp-lib)
ELASTICSEARCH 131072
異常狀況 262144
LOGGERS 524288
COUCHBASE 1048576
TWIG 2097152
SYMSONY 4194304
KOHANA 134217728
GOOGLE_PUBSUB 268435456

旗標不會依名稱顯示。您必須使用其數值來停用檢測。

如果您需要這些設定的協助，請聯絡 IBM 支援中心。

啟用 PHP 追蹤器 2.0

在追蹤 PHP 應用程式期間，如果您遇到 Instana 代理程式的效能問題 (例如高 CPU 使用率) ，您可以使用 Instana PHP Tracer 2.0 來取得更好的結果。

重要事項: PHP Tracer 2.0 不支援所有 PHP 版本。如需相關資訊，請參閱支援的 PHP 版本。

第一次配置 PHP 追蹤器 2.0

如果您是第一次設定 PHP Tracer 2.0 ，請完成下列步驟:

如果您使用 Web 伺服器 (例如 Apache 或 NGINX) ，請執行下列指令來停止它和 PHP FastCGI Process Manager (PHP-FPM) 常駐程式:
```
systemctl stop apache2
```
```
systemctl stop php<version>-fpm
```
範例：
```
systemctl stop php7.4-fpm
```

使用下列配置來更新代理程式配置檔 /opt/instana/agent/etc/instana/configuration.yaml :

com.instana.plugin.php:
  tracing:
    enabled: true
    enableHttpTraces: true 
    installExtension: true
    pinextensionVersion: 2.0.1

執行下列指令，以啟動 Web 伺服器的常駐程序，例如 Apache 2 或 NGINX:
```
systemctl daemon-reload
```
```
systemctl start apache2
```
```
systemctl start php<version>-fpm
```

啟動或重新啟動 Instana 代理程式，並使用下列指令來檢查其狀態:

systemctl start instana-agent

systemctl restart instana-agent

systemctl status instana-agent

驗證下列 ini 設定在 zzz-instana.ini 檔案中是否具有正確的值。若要列出這些 Instana 特定設定，請使用下列指令:
```
php-fpm<version> -i |grep instana
```
- instana.use_agent_endpoint: 此值必須設為 1。
- instana.agent_endpoint: 此值必須設為 http://127.0.0.1:42699。
- instana.pid_in_root_namespace: 如果您將 mod_php 與 Apache搭配使用，此值必須符合 Apache 處理程序 ID。如果透過 Apache配置 FPM ，則此值必須是 PHP-FPM 主要處理程序 ID。如果值不符，請編輯 instana.pid_in_root_namespace ，並使用下列指令來重新載入 FPM 或 Apache 常駐程式:
```
systemctl reload php<version>-fpm
```
```
systemctl reload apache2
```
附註: 您可以使用下列指令來擷取程序 ID:
```
ps ax | grep fpm
```
```
ps -ax| grep apache2
```
在 Instana 使用者介面中的 PHP 執行時期儀表板上，驗證 PHP 延伸版本和 zzz-instana.ini 是否存在。此資訊可能需要一些時間才能反映在使用者介面中。如果您重新啟動 FPM ，請確定處理程序 ID 符合主要處理程序 ID。

升級至 PHP 追蹤器 2.0

如果您使用 PHP Tracer 1.0，請完成下列步驟來升級至 PHP Tracer 2.0:

執行下列指令，以停止 Instana 代理程式及 PHP-FPM 和 Apache 常駐程式:

systemctl stop instana-agent

systemctl stop apache2

systemctl stop php<version>-fpm

選用: 從 php extension_dir extension_dir 和 php ini 掃描 --with-config-file-scan-dir 目錄中備份 instana.so 和 zzz-instana.ini 配置檔。
從 php extension_dir extension_dir 和 php ini 掃描 --with-config-file-scan-dir 目錄中移除 instana.so 二進位檔和 zzz-instana.ini 檔案。
若要啟用 PHP Tracer 2.0，請遵循第一次配置 PHP Tracer 2.0 小節中所概述的相同步驟。

解除安裝 Instana PHP 追蹤延伸

若要解除安裝 Instana PHP 追蹤延伸，您需要先停用 PHP 感應器啟動。否則，它會重新安裝延伸。與安裝不同，解除安裝不是自動的，且需要進一步的手動步驟。

停用 PHP 追蹤感應器

若要停用「PHP 追蹤」感應器，請完成下列步驟:

使用文字編輯器開啟 <agent_install_dir>/etc/instana/configuration.yml 。即會顯示下列項目:

com.instana.plugin.php:
  tracing:
    enabled: true

將 enabled: true 變更為 enabled: false。因為依預設會啟用追蹤，所以註解 false 不會停用追蹤。

或者，您也可以設定 installExtension: false 來停用 PHP 追蹤延伸的安裝，但讓感應器能夠接受追蹤。

您需要重新啟動代理程式，才能套用變更。

附註: 停用感應器不會停用追蹤延伸。

停用 PHP 追蹤延伸

當 PHP 感應器安裝延伸時，也會啟用 PHP 安裝的延伸。啟用延伸表示 PHP 感應器會將 zzz-instana.ini 檔案放置在 Additional Ini 檔案資料夾中，或直接在 php.ini中啟用它。

若要找出啟用它的位置，請執行您已啟用追蹤的 PHP 二進位檔。下列範例顯示 PHP-FPM 的 PHP 二進位:

    $> php-fpm7.0 -i | egrep "^(Scan|Loaded)"
    Loaded Configuration File => /etc/php/7.0/fpm/php.ini
    Scan this dir for additional .ini files => /etc/php/7.0/fpm/conf.d

在此範例中， zzz-instana.ini 檔案位於 /etc/php/7.0/fpm/conf.d中。如果沒有可用的 Additional Ini 檔案資料夾，或 zzz-instana.ini 檔案不存在於該位置，請改為檢查 php.ini 。在此範例中，檔案位於 /etc/php/7.0/fpm/php.ini中。

附註: 若為具有 mod_php 的 Apache ，請將含有內容 <?php phpinfo(); 的 PHP 檔放入 Apache 上可存取 Web 的位置，並在瀏覽器中開啟它，以取得相同資訊。

若要停用 PHP 追蹤延伸，請完成下列步驟:

在編輯器中開啟適當的 ini 檔案，並在 extension=/path/to/instana.so 行中以分號 (;) 作為字首，如下所示。在這一行中新增分號註解。

;extension=/path/to/instana.so

或者，完全移除明細行 extension=/path/to/instana.so 。 附註: 如果您想要在稍後啟用延伸，請不要移除它。
如果您具有 zzz-instana.ini 檔案，則也可以完全移除該檔案，如下所示:
```
$> sudo rm /etc/php/7.0/fpm/conf.d/zzz-instana.ini
```
重要事項: 請勿移除整個 php.ini 檔案。
如果您使用預先分出的工作者節點，則需要立即重新啟動 PHP 主要處理程序。否則，延伸會在記憶體中保持作用中。

附註: 停用延伸不會將它從系統中移除。

移除 PHP 追蹤延伸

PHP 在找不到延伸時，會記載啟動錯誤，因此在移除延伸之前，您也必須停用它。如需相關資訊，請參閱停用 PHP 追蹤延伸。

PHP 感應器會將 Instana PHP 追蹤延伸放入 php.ini的 extension_dir 設定中所提供的目錄。若要找出設定，請執行您已啟用追蹤的 PHP 二進位檔。下列範例顯示 PHP-FPM 的 PHP 二進位:

$> php-fpm7.0 -i | egrep ^extension_dir
extension_dir => /usr/lib/php/20151012 => /usr/lib/php/ext

附註: 若為具有 mod_php 的 Apache ，請將含有內容 <?php phpinfo(); 的 PHP 檔放入 Apache 上可存取 Web 的位置，並在瀏覽器中開啟它，以取得相同資訊。

PHP 感應器只會使用第一個值，因此在範例中，您可以找到副檔名 at/usr/lib/php/20151012。延伸的路徑也在 php.ini 或 instana.ini中提供。

若要移除延伸，請執行下列指令:

$> sudo rm /usr/lib/php/20151012/instana.so

如果您使用預先分出的工作者節點，且在停用延伸時尚未重新啟動 PHP 主要處理程序，則需要立即重新啟動，變更才會生效。

自動重新啟動

PHP 感應器會自動下載並安裝 PHP 設定的適當 PHP 追蹤延伸。此外，感應器還會嘗試重新啟動 PHP 環境，以將延伸載入記憶體。 Apache 和 PHP-FPM 目前支援自動重新啟動。 PHP-CGI 環境需要手動或 Script 化處理。

您可以透過 notificationScript 配置設定，變更 PHP 感應器嘗試重新啟動 PHP 環境的方式。此設定會採用可執行 Shell Script 的絕對路徑。每當目前安裝的追蹤延伸版本與已安裝的代理程式版本不同時，即會觸發此 Script。

當順利配置並執行此 Script 時，它會置換自動重新啟動的預設機制。與預設機制不同， Script 會針對任何 SAPI 執行，因此可以用來針對 PHP-CGI 環境自動重新啟動。如果您想要完全停用自動重新啟動，請配置空的 Script。

PHP 感應器會設定下列環境變數來執行 Script:

INSTANA_EXT_VERSION_OLD = the version of the tracing extension currently in memory
INSTANA_EXT_VERSION_NEW = the version of the tracing extension after a restart
INSTANA_PID_HOST = the PID of the process on the host, e.g. your Apache, PHP-FPM or PHP-CGI
INSTANA_PID_CONTAINER = the PID the host process has in a container (if applicable)
INSTANA_CONTAINER = the ID/name of the container the process is running in (if applicable)

下列範例顯示將延伸變更記載至檔案並重新啟動 Apache的 Script:

    #!/bin/bash
    echo "Found new tracing extension." >> php_update.log;
    echo "INSTANA_EXT_VERSION_OLD=$INSTANA_EXT_VERSION_OLD" >> php_update.log;
    echo "INSTANA_EXT_VERSION_NEW=$INSTANA_EXT_VERSION_NEW" >> php_update.log;
    echo "INSTANA_PID_HOST=$INSTANA_PID_HOST" >> php_update.log;
    echo "INSTANA_PID_CONTAINER=$INSTANA_PID_CONTAINER" >> php_update.log;
    echo "INSTANA_CONTAINER=$INSTANA_CONTAINER" >> php_update.log;
    echo "restarting apache" >> php_update.log;
    apachectl -k graceful >> php_update.log;

如果 Apache 在儲存器內執行，請將範例 Script 中的最後一行取代為下列這一行:

docker exec $INSTANA_CONTAINER apachectl -k graceful;

若為 PHP-FPM ，您可以傳送 SIGUSR2 以循序重新啟動它，如下列範例所示:

docker exec $INSTANA_CONTAINER kill -USR2 $INSTANA_PID_CONTAINER;

循序重新啟動會將 PHP 延伸載入記憶體，而不重新啟動主要處理程序。因此，即使處理程序在儲存器內以 PID 1 執行，此載入仍會運作。如果您無法或不想使用重新啟動方法，則也可以建立執行中容器實例的 Snapshot ，停止它，並輕鬆開啟新的實例:

    #!/bin/bash
    IMAGE_HASH=$(docker inspect --format='{{.Config.Image}}' $INSTANA_CONTAINER)
    IMAGE_NAME=$(docker images | grep $IMAGE_HASH | awk '{print $1}')
    IMAGE_TAG="instana-php-$INSTANA_EXT_VERSION_NEW"
    docker commit $INSTANA_CONTAINER $IMAGE_NAME:$IMAGE_TAG &&
    docker stop $INSTANA_CONTAINER &&
    docker run -d --rm $IMAGE_NAME:$IMAGE_TAG

此動作會使用傳遞至 Script 的儲存器 ID 來尋找儲存器映像檔的名稱。然後，它會將目前執行中的儲存器確定至以新的 PHP 延伸版本號碼標示的新映像檔。然後，它會停止原始容器，並從新標記的映像檔啟動容器。雖然此動作會再次觸發 PHP 感應器中的安裝常式，但不會再次觸發通知 Script ，因為已安裝延伸。

這些範例假設您使用 Docker 作為儲存器引擎。但是，因為觸發的 Shell Script 完全由您控制，所以您可以放置任何您需要的邏輯，讓自動重新啟動適用於您的設定。