PHP のトレース機能を有効にして設定する

トレースを無効にする設定を行うには、以下のいずれかの方法を使用してください：

• カスタム設定ファイル
• Instana エージェント configuration.yaml ファイル

設定の優先順位に関する詳細については、 「スパンの無効化に関する設定の優先順位」 を参照してください。

スパン無効化の設定構文に関する詳細については、 「トレースの無効化」 を参照してください。

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

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

「自動インスツルメンテーションが適用されたライブラリおよびフレームワーク」 の表に記載されているすべてのインスツルメンテーション識別子を使用して、特定のスパンタイプに対するスパン無効化ルールを設定できます。

スパン無効化ルールは、優先順位の高い順から低い順に、以下の順序で適用されます：

1. 環境変数 INSTANA_CONFIG_PATH を通じて渡されるカスタム設定ファイルから、無効化ルールを適用します。
2. INI instana.disabled_instrumentation 設定でスパン無効化が設定されています。
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_CONFIG_PATH 変数が優先されるため、INI設定 instana.disabled_instrumentation は無視されます。 したがって、環境 INSTANA_CONFIG_PATH 変数で指定された設定ファイルを通じて無効化されていないすべての計測機能は有効になります。

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

カスタム設定ファイル、環境変数、または Instana エージェントの設定を使用して、スタックトレースを設定します。

スタックトレースを設定するには、以下のいずれかの方法を使用してください：

• カスタム設定ファイル
• 環境変数
• Instana エージェント configuration.yaml ファイル

異なる設定方法間の設定の優先順位に関する詳細については、 「スタックトレースの設定優先順位」を参照してください。

YAML という構文を使用して、スタックトレースのレベルと深さの設定を行います。

スタックトレースの設定を行うには、以下の YAML 構文を使用してください：

# Use 'tracing' section if using custom configuration file
# Use 'com.instana.tracing' section if using agent configuration.yaml file
tracing:
  global:
    stack-trace: <string>
    stack-trace-length: <int>

スタックトレースの設定は、カスタム設定ファイルからエージェント設定へと、優先順位の高い順に適用されます。

スタックトレースの設定は、優先順位の高い順から低い順に、以下の順序で適用されます：

1. INSTANA_CONFIG_PATH 環境変数を通じて渡されるカスタム設定ファイルからのスタックトレース設定。
2. スタックトレースの設定は、環境変数 INSTANA_STACK_TRACE および INSTANA_STACK_TRACE_LENGTH を通じて行われます。
3. スタックトレースの長さは、INI設定で instana.backtrace_limit 指定します。
4. エージェント configuration.yaml のファイルからのスタックトレースの設定。

前のセクションで挙げたさまざまな設定方法において、スタックトレースモードおよびスタックトレースの長さに関する設定の優先順位は、それぞれ個別に評価され、適用されます。

PrivateTmp ディレクティブを使用してsystemdサービスを設定し、 PHP Tracerが YAML の設定にアクセスできるようにします。

PHP のランタイムが、`directive` PrivateTmp で設定された systemd サービスである場合、 PHP のプロセスには、ホストのシステム一時ディレクトリとは分離された独自の一時ディレクトリが割り当てられます。 PHP センサーはプロセスの一時ディレクトリに書き込みができないため、このような PHP ランタイム環境では、 PHP Tracerが YAML の設定を読み取ることができません。

PrivateTmpPHP のsystemdサービスでこの設定を無効化することが要件に合わない場合は、代わりにカスタム設定ファイルを使用して、 PHP のsystemdサービスで設定を無効化することなく PrivateTmp 、 スパン無効化ルール、 スパンフィルタリングルール、 およびスタックトレースを設定することができます。

あるいは、 PHP の実行環境において、設定 PrivateTmp によって提供される一時ファイルシステムの分離機能が必要ない場合は、以下の手順に従って PHP のsystemdサービスでを無効 PrivateTmp にし、 スパン無効化ルール、 スパンフィルタリングルール、 およびスタックトレースの設定には引き続きエージェント configuration.yaml ファイルを使用することができます：

1. 次のコマンドを実行して、 PHP の systemd サービスユニットファイルを編集します

   sudo systemctl edit <systemd-service-unit-name>
   # systemd service names are usually named like apache2.service, php8.3-fpm.service, etc.,

2. セクション [Service] 内の ディレクティブを PrivateTmp に false 設定します：

   [Service]
   PrivateTmp=false

3. systemd 構成の再ロード

   systemctl daemon-reload

4. 変更を反映させるには、systemd サービスを再起動してください。

IISのワーカープロセスが、 Windows の一時フォルダにアクセスできない場合があります。 一時フォルダへのアクセス権限が不十分な原因は、ワーカープロセスを実行するために使用されているアプリケーションプールの識別子に、一時フォルダに対する十分な読み取りまたは書き込み権限がないためです。 このアクセスに関する問題を解決するには、以下の手順を実行してください：

1. PowerShell のターミナルで次のコマンドを実行し、アプリケーションプールのIDを確認してください：

   & $env:windir\system32\inetsrv\appcmd.exe list apppool <your AppPool> /text:processModel.identityType
    

2. IDが異なる場合は ApplicationPoolIdentity、次のコマンドを実行してIDを更新してください：

   & $env:windir\system32\inetsrv\appcmd.exe set AppPool <your AppPool> -processModel.identityType:ApplicationPoolIdentity
    

3. 変更を反映させるには、アプリケーションプールを再起動してください：

   & $env:windir\system32\inetsrv\appcmd.exe recycle apppool <your AppPool>
    

   IISサーバーは、 ApplicationPoolIdentityそのIDで実行されているアプリケーションプールを検出し、そのアプリケーションプールの名前を持つ仮想ユーザーを作成します。

4. PHP ランタイム（つまり、IISワーカープロセス）に <SYSTEM_TEMP> ディレクトリへの読み取りアクセス権を付与するには、次のコマンドを実行します

   
   icacls "<SYSTEM_TEMP>" /grant "IIS APPPOOL\<your AppPool>:(OI)(CI)R" /T /C
    

通知スクリプトは、 PHP の実行ごとに1回実行されます。つまり、同じ PHP 実行ファイルを実行しているすべてのプロセスで、このスクリプトがトリガーされるとは限りません。 PHP のトレース拡張機能をメモリに読み込むには、スクリプトで、 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 トレース拡張機能の自動インストールを無効にするには、エージェントの`agent configuration.yaml .conf`ファイル内の`Tracing` com.instana.plugin.php セクションで false 、 tracing.installExtension `Tracing`を`false`に設定します

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

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

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

1. 以下の前提条件を確認します。

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

2. PHP アプリケーションを実行しているサービス上で、次の reload コマンドを実行して、 PHP トレース拡張機能を再読み込みします：

   • Apacheの場合:

     systemctl reload apache2
      

   • PHP -FPM 向け：

     systemctl reload php<version>-fpm
      

     再ロード・コマンドの < version> を、システムにインストールされている実際のバージョンに置き換えます。

それでも Instana のUIに何の痕跡も見当たらず、お使いのOSがデフォルトでSELinuxを搭載しているか、セキュリティ上の理由で環境にSELinuxを追加している場合は、SELinuxがこの問題の原因である可能性があります。

PHP のTracer拡張機能は、 Unix TCP ソケットを介して PHP デーモンと通信し、 <socket path>TCP/IP のポート42699を介して Instana エージェントと通信します。 SELinuxが強制モードに設定されている場合、SELinuxで許可するように設定されていない限り、 PHP 拡張機能とデーモン間の通信は阻止されます。

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

1. SELinuxを一時的に無効にしてください。
2. PHP デーモンを再起動します。

SELinuxが問題の原因であると特定された場合、以下のいずれかの方法により解決できます：

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

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

• SELinuxを許容モードに設定します。このモードでは、サービスは制限なく動作します。 サーバーを再起動することで、デフォルト設定に戻すことができます。 SELinuxを許容モードに設定するには、 「SELinuxの許容モード」 を参照してください。

• SELinux を無効にする： Instana は、セキュリティソフトウェアを無効にするよう積極的に推奨しているわけではありません。 適切かつ安全な方法は、SELinuxポリシーを作成することです。 ただし、SELinuxを無効にする場合は、 「SELinuxの無効化」 を参照してください。

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

• 環境変数を使用してログ記録を有効にします。
  1. ログレベルをデバッグに設定するには、をに INSTANA_DEBUG 設定 TRUE するか、 INSTANA_LOG_LEVEL=4

• INI ファイルを使用してログ記録を有効にします。

  1. PHPzzz-instana.ini のインストール先のスキャンディレクトリ内で、という名前のファイルを探してください。 例えば、 php --ini | grep zzz-instana.ini または php-fpm<version> -i | grep zzz-instana.ini を実行すると、その場所が表示されます。

  2. 行 instana.log_level=4 を zzz-instana.iniに追加します。

  3. 選択した PHP ランタイムを実行する際は、出力に何らかのログが記録されていること、および拡張機能が有効になっていることを確認してください。 例えば、 php --ri instana または php-fpm<version> -i | grep instana を実行して検証することができます。

     例:

     [instana.INFO] Initializing, logging at level 4
      

  4. こちらの説明に従って、 PHP トレース拡張機能を再読み込みしてください。 この手順を省略すると、結果としてログが記録されなくなります。

「 PHP 」トレース拡張機能を手動でインストールするには、以下の手順に従ってください：

1. 「 Instana 」の「 PHP 」トレース拡張機能を、以下の手順でダウンロードしてください：

   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 版については、メジャーバージョン番号とマイナーバージョン番号を指定してください。 たとえば、 PHP 用の Instana 拡張機能（ 8.4.12 ）をダウンロードするには、フラグを指定してシェ -p 8.4ルスクリプトを実行します。

      • OpenSSL 版の場合は、 OpenSSL 1.1-s ssl1 に対応した拡張機能をダウンロードするにはオプションを使用するか、 OpenSSL に対応した拡張機能をダウンロードするには 3.x-s ssl3 を使用してください。

      • Instana 拡張機能の場合、デフォルト値は であり release、利用可能な最新バージョンがダウンロードされます。 特定のバージョンのアーティファクトをダウンロードするには、` -v flag` を使用してください。 たとえば、スクリプトを次のように実行して -v 4.7.0 、リリース版 4.7.0 の拡張機能をダウンロードします。

      • スクリプトで使用可能なすべてのオプションを確認するには、次のコマンドを実行してください：

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

2. 以下の手順で拡張機能をインストールしてください：

   1. ダウンロードした .so ファイルを PHP のCLI拡張機能ディレクトリに移動してください。

   2. 以下の例に示すようにINIファイルを作成し、 zzz-instana.iniPHP 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 のトレースを無効にする 」の手順に従うと、 PHP のトレースが完全に無効化され、 PHP ランタイムから PHP Tracing拡張機能も削除されます。

この手順の実行中にエラーが発生し、 PHP のトレース機能を手動で無効にして「 PHP Tracing」拡張機能をアンインストールする場合は、以下の手順に従ってください

1. エージェント configuration.yaml ファイルで、 PHP のトレースが無効になっていることを確認してください。具体的には、次のように設定します：

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

   この設定により、 PHP センサーが PHP のトレース拡張機能を再度インストールするのを防ぎます。

2. PHP のINI設定ファイルで、 PHP トレース拡張機能を無効にしてください。 「 PHP トレース拡張機能の無効化」 を参照してください。

3. システムから「 PHP 」トレース拡張機能のファイルを削除してください。 「 PHP トレース拡張機能ファイルの削除」 を参照してください。