PHP トレースの有効化と設定

環境変数を通してトレースを無効にするには、環境変数 INSTANA_CONFIG_PATH を設定します。

たとえば、すべてのデータベース呼び出し ( MongoDB を除く) とすべてのロギングフレームワークのトレースを無効にするには、次のコードを別の YAML ファイルにコピーします：

tracing:
  disable:
    - databases: true
    - mongodb: false
    - logging: true
 

環境変数 INSTANA_CONFIG_PATH を次のようにコンテンツを配置するYAMLファイルの絶対パスに設定します：

INSTANA_CONFIG_PATH=<your YAML file>
 

Instana エージェント設定でトレースを無効にするには、エージェント configuration.yaml ファイルの com.instana.tracing.disable セクションでトレースを無効にします。

すべてのデータベース呼び出し（ Redis を除く）とすべてのロギングフレームワークのトレースを無効にするには、次の例に示すように、エージェント configuration.yaml ファイルの com.instana.tracing セクションを更新します：

com.instana.tracing:
  disable:
    - databases: true
    - redis: false
    - logging: true
 

設定のカスタマイズの詳細については、 トレースを無効にするを参照してください。

あるカテゴリのトレースを無効にすると、そのカテゴリの下にあるすべてのライブラリのスパン生成が無効になります。 PHP Tracer がサポートするカテゴリの一覧は以下のとおりです：

• データベース
• フレームワーク
• メッセージング
• プロトコル
• ロギング
• テンプレート処理
• その他 （カテゴリーキーはありません）

スパン無効化ルールは、以下の優先順位で適用される：

1. 環境変数を介して渡されるコンフィギュレーション・ファイルのルールを無効にする。 INSTANA_CONFIG_PATH 環境変数を通して渡されます。
2. instana.disabled_instrumentation iniの設定でスパン無効化。
3. エージェント configuration.yaml ファイルからルールを無効にする。

この優先順位はフィーチャーレベルで強制される。 PHPランタイムがある機能で複数の設定を検出した場合、最も優先順位の高い設定からスパン無効化ルールを適用します。 例えば、PHPランタイムが以下のようなスパン無効化ルールを環境変数 INSTANA_CONFIG_PATH 環境変数

com.instana.tracing:
  disable:
    - logging: true
    - databases: true
    - redis: false
 

そして、同じランタイムには次のようなini設定がある：

instana.disabled_instrumentation=24 ; disables redis (16) and curl (8) instrumentations
 

この設定例では、PHP Tracer は以下のように動作します：

• すべてのロギング・ライブラリのトレースが無効になる。
• Redis を除くすべてのデータベースのトレースは無効になっています。

環境変数が優先されるため、 instana.disabled_instrumentation iniの設定は無視される。 INSTANA_CONFIG_PATH 環境変数が優先される。 したがって、環境変数で指定されたコンフィギュレーション・ファイルによって無効化されていないインスツルメンテーションはすべて有効化される。 INSTANA_CONFIG_PATH 環境変数で指定されたコンフィギュレーション・ファイルによって無効化されていないインスツルメンテーションはすべて有効化される。

スパン無効化ルールが、環境変数とエージェント ファイルの両方を通して設定されている場合、 ファイルのルールは無視される。 INSTANA_CONFIG_PATH スパン無効化ルールが環境変数とエージェント configuration.yaml ファイルの両方を通して設定されている場合、 configuration.yaml ファイルのルールは無視されます。

PHPセンサーは、エージェント configuration.yaml ファイルの変更を検知し、セクション com.instana.tracing.disable のコピーを、 <System Temp>/instana-php/instana_span_filer_config.yaml にある別のファイルに作成する。 生成されたファイルの絶対パスは instana.span_filter_config_file ini の設定に設定され、 PHP Tracer は PHP ランタイムを再起動することなく configuration.yaml ファイルへの変更を検知して適用します。 したがって、エージェント configuration.yaml ファイルを使用してルールの設定や無効化を行う場合、PHP ランタイムはシステムの temp フォルダにアクセスできる必要があります。

以下の節では、PHPランタイムがシステムのtempフォルダに十分にアクセスできるようにするために、環境によっては必要となる追加の手順を説明します。

通知スクリプトはPHPの実行時間ごとに一度だけ実行されるため、同じPHP実行ファイルを実行しているすべてのプロセスでスクリプトが起動されるとは限りません。 PHP Tracing 拡張モジュールをメモリに読み込むには、スクリプトが PHP 実行ファイルから実行されているすべてのプロセスを再起動するようにしなければなりません。

このスクリプトが設定され、正常に実行されると、自動再起動のデフォルトメカニズムを上書きする。 デフォルトの仕組みとは異なり、このスクリプトはどの SAPI に対しても実行されます。 そのため、PHP-CGI 環境での再起動の自動化に使用できます。 自動再起動を完全に無効にしたい場合は、空のスクリプトを設定する。

PHP センサーは、スクリプト実行のために以下の環境変数を設定する：

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 を再起動するスクリプトです：

#!/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 をコンテナ内で実行する場合は、サンプル・スクリプトの最後の行を次の行に置き換える：

docker exec $INSTANA_CONTAINER apachectl -k graceful;
 

PHP-FPMの場合は、次の例のように SIGUSR2 を送信することで 優雅に再起動させることができる：

docker exec $INSTANA_CONTAINER kill -USR2 $INSTANA_PID_CONTAINER;
 

グレースフル・リスタートは、マスタープロセスを再起動せずに PHP 拡張モジュールをメモリにロードします。 そのため、このロードは、コンテナ内でプロセスがPID 1として実行されている場合でも機能する。 再起動の方法が使えない、あるいは使いたくない場合は、実行中のコンテナ・インスタンスのスナップショットを作成して停止し、新しいインスタンスを簡単に開くこともできる：

#!/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
 

このアクションは、スクリプトに渡されたコンテナIDを使用して、コンテナイメージの名前を検索します。 そして、現在実行中のコンテナを、新しい PHP 拡張モジュールのバージョン番号が付与された新しいイメージにコミットします。 その後、元のコンテナを停止し、新しくタグ付けされた画像からコンテナを開始する。 このアクションはPHPセンサーのインストールルーチンを再度トリガーしますが、拡張機能はすでにインストールされているため、通知スクリプトを再度トリガーすることはありません。

これらの例は、 Docker をコンテナ・エンジンとして使用していることを前提としている。 しかし、トリガーされたシェルスクリプトは完全にあなたのコントロール下にあるので、あなたのセットアップに自動再起動を機能させるために必要なロジックを置くことができる。

新しく検出された PHP ランタイムへの PHP Tracing 拡張モジュールの自動インストールを無効にするには、 エージェントファイル false のセクションで tracing.installExtension を に設定します。 com.instana.plugin.php セクションを configuration.yaml に設定します：

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

Pleskを使用している場合は、 plesk bin php_handler --reread を実行する必要があります。

PHP アプリケーションの Instana UI にトレースが表示されない場合は、次の手順を実行してください：

1. 以下の前提条件を確認する：

   • PHPセンサーが有効になっている。 詳細は PHP トレースを無効にする を参照ください。
   • PHP Tracing 拡張バイナリが利用可能です。 詳細は PHP Tracing 拡張モジュールを無効にする を参照ください。
   • PHP Tracing 拡張は、エージェント設定ファイルで有効になっています。 詳細は PHP Tracing 拡張ファイルの削除 を参照ください。

2. PHP Tracing 拡張モジュールを再読み込みするには、以下のコマンドを実行します。 reload コマンドを実行します：

   • Apache ：

     systemctl reload apache2
      

   • PHP-FPM の場合：

     systemctl reload php<version>-fpm
      

     reloadコマンドの <version>は、システムにインストールされている実際のバージョンに置き換えてください。

それでも Instana UI にトレースが表示されず、オペレーティングシステムにデフォルトで SELinux が含まれているか、セキュリティ目的で環境に追加されている場合、SELinux が問題の原因である可能性があります。

PHP Tracer エクステンションは、PHP デーモンとは Unix TCP ソケット <socket path> で通信し、Instana エージェントとは TCP/IP ポート 42699 で通信します。 SELinux が強制モードに設定されている場合、SELinux が許可するように設定されていない限り、PHP 拡張モジュールとデーモンが互いに通信することを防ぎます。

この問題が SELinux のせいであるかどうかを調べるには、 /var/log/audit/audit.log で PHP デーモンのサイレント拒否が記録されていないか確認してください。 または、以下の手順を実行してスモークテストを行うこともできます：

1. SELinuxを一時的に無効にする。
2. PHPデーモンを再起動します。

SELinuxが問題の原因として特定された場合、以下のいずれかのオプションを使用することで解決できる：

• PHP Tracer が通信できるように SELinux を設定します：SELinux を使用すると、独自のセキュリティポリシーに従ってカスタムポリシーを設定し、通信を許可することができます。 SELinuxポリシーの作成と変更の詳細については、以下のリンクを参照してください：

  • CentOS SELinux ドキュメント
  • RHEL SELinux ドキュメント

• SELinuxをパーミッシブ・モードに設定する：このモードでは、サービスは制限なしで動作することができます。 サーバーを再起動することで、デフォルト設定に戻すことができます。 SELinuxをパーミッシブ・モードに設定するには、 SELinuxパーミッシブ・モードを参照のこと。

• SELinux を無効にします：Instana は、セキュリティソフトウェアを無効にすることを積極的に推奨していません。 正しく安全なアプローチは、SELinuxポリシーを作成することである。 ただし、SELinux を無効にする場合は、 Linux を無効にする」を参照してください。

デフォルトでは、ロギングはオフになっている。 有効にするには、以下の手順を参照してください。

• 環境変数を使ってロギングを有効にする。

1. ログレベルをデバッグに設定するには、 INSTANA_DEBUG を TRUE または INSTANA_LOG_LEVEL=4

• INIファイルを使用してロギングを有効にする。

1. PHPをインストールしたディレクトリのscanディレクトリにある zzz-instana.ini という名前のファイルを探します。 たとえば、 php --ini | grep zzz-instana.ini や php-fpm<version> -i | grep zzz-instana.ini を実行すると、その場所がわかる。

2. zzz-instana.ini に instana.log_level=4 という行を追加する。

3. 選択した PHP ランタイムを実行する際には、ログが出力され、 拡張モジュールが有効になっていることを確認してください。 例えば、 php --ri instana や php-fpm<version> -i | grep instana を実行して検証することができる。

   例:

   [instana.INFO] Initializing, logging at level 4
    

4. ここで説明されているように、PHP tracing extension をリロードします。 このステップをスキップすると、最終的にログが記録されなくなる。

ログは、PHP トレース拡張モジュールがインストールされている PHP ランタイムに送られます。 このため、正確な位置はその構成に大きく左右される。 通常、 Apache2 の場合は /var/log/apache2/error.log を、PHP-FPM の場合は /var/log/php<version>-fpm.log を指定します。

PHP Tracing 拡張モジュールを手動でインストールするには、以下の手順を実行します：

1. Instana PHP Tracing エクステンションを次のようにダウンロードします：

   1. 以下のリポジトリからシェルスクリプトをダウンロードする：

      https://artifact-public.instana.io/artifactory/shared/com/instana/php/instana-ext-download-script/php-instana-ext-download-script.sh
       

   2. シェルスクリプトを実行して、あなたの環境に適した拡張機能をダウンロードしてください。 次のコマンドは利用可能なオプションを示す：

      ./php-instana-ext-download-script.sh -a <aarch64/x86_64> -l <musl/glibc> -p <PHP version> -t <NTS/ZTS> -d <serverless/native> -s <OpenSSL version> -v <Instana extension version>
       

      • PHPのバージョンは、メジャーバージョンとマイナーバージョンを指定してください。 例えば、Instana extension for PHP 8.4.12 をダウンロードするには、フラグ -p 8.4 を指定してシェルスクリプトを実行します。

      • OpenSSL バージョンの場合、 OpenSSL 1.1 をサポートするエクステンションをダウンロードするには -s ssl1 オプションを、 OpenSSL 3.x をサポートするエクステンションをダウンロードするには -s ssl3 オプションを使用する。

      • Instana 拡張機能のバージョンについては、デフォルト値は release で、利用可能な最新バージョンをダウンロードします。 特定のバージョンのアーティファクトをダウンロードするには、 -v フラグを使用します。 例えば、 -v 4.7.0 でスクリプトを実行すると、リリースバージョン 4.7.0 の拡張機能がダウンロードされます。

      • スクリプトで使用可能なすべてのオプションを表示するには、次のコマンドを実行します：

        ./php-instana-ext-download-script.sh
         

2. 以下のようにエクステンションをインストールする：

   1. ダウンロードした .so ファイルを PHP CLI 拡張モジュールディレクトリに移動します。

   2. 次の例のように INI ファイル zzz-instana.ini を作成し、PHP CLI 追加 INI ディレクトリに保存します。 <hostIP> を Instana エージェントホストの IP アドレスに置き換えて、エージェントが PHP 環境から到達できるようにします。

      ; this file was automatically generated by Instana
      ;
      ; any changes made to this file are expected to be overwritten when
      ; a new version of the Instana PHP Tracer extension is installed
      [instana]
      extension=<php cli extension dir path where extension.so file is placed>
      instana.socket=<hostIP>:16816
      instana.agent_endpoint=http://<hostIP>:42699
      instana.use_agent_endpoint=1
      instana.auto_profile_socket=tcp://<hostIP>:42699
      instana.enable_auto_profile=0
      instana.secrets_matcher=contains-ignore-case
      instana.secrets_list="key,pass,secret"
      instana.extra_http_headers=
      instana.pid_in_root_namespace=<pid of PHP process in hostnamespace>
      instana.enable_cli=1
       

PHP Tracing を無効にするで説明した手順を実行すると、 PHP トレースが完全に無効になります。

この手順でエラーが発生し、手動で PHP トレースを無効にして PHP Tracing 拡張モジュールをアンインストールしたい場合は、 以下の手順を実行します：

1. 以下のように、エージェント configuration.yaml ファイルで PHP トレースが無効になっていることを確認してください：

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

   この設定により、PHP センサーが PHP Tracing 拡張モジュールを再インストールすることを防ぎます。

2. PHP INI 設定で PHP Tracing 拡張モジュールを無効にする。 PHP Tracing 拡張モジュールを無効にする を参照ください。

3. PHP Tracing 拡張ファイルをシステムから削除する。 PHP Tracing 拡張ファイルの削除 を参照ください。