PHP 跟踪扩展

PHP 扩展

要运行 PHP Tracer，必须有 JSON 扩展。

禁用 PHP 跟踪传感器

要禁用 PHP 跟踪传感器，请完成以下步骤：

1. 在文本编辑器中打开<agent_install_dir>/etc/instana/configuration.yml。 显示以下条目：

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

2. 将enabled: true更改为enabled: false。 因为默认情况下已启用跟踪功能，所以注释 false 并不会禁用跟踪功能。

或者，您也可以设置 installExtension: false 以禁用 PHP 跟踪扩展的安装，但保持传感器可接受跟踪。

您需要重新启动该代理程序以应用更改。

禁用传感器不会禁用跟踪扩展。

禁用 PHP 跟踪扩展

当 PHP 传感器安装扩展时，它也会为您的 PHP 安装启用扩展。 启用扩展意味着 PHP 传感器将 zzz-instana.ini 文件放入 Additional Ini 文件夹，或直接在 php.ini.NET 文件夹中启用。

要了解它的启用位置，请运行您对其启用了跟踪的 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。

在 Windows 系统中，在 powershell 中运行以下命令，以获取 php.ini 文件的位置或 PHP-CGI 的 Additional Ini 文件夹的位置：

PS C:\> php-cgi -i | Select-String -Pattern '(Scan|Loaded Configuration)' | ForEach-Object { ($_ -replace '<br\s*/?>', "`n") -replace '<[^>]+>', ''}
Loaded Configuration File C:\Php\php.ini
Scan this dir for additional .ini files (none)

对于使用 mod_php 的 Apache ，可将内容为 <?php phpinfo(); 的 PHP 文件放到 Apache 上可访问网络的位置，然后在浏览器中打开该文件，以获取相同的信息。

要禁用 PHP 跟踪扩展，请完成以下步骤：

1. 用编辑器打开相应的 ini 文件，并在 extension=/path/to/instana.so 行中添加分号 (;) 作为前缀，如下所示。 添加分号可注释该行。

   ;extension=/path/to/instana.so

   或者，完全删除行 extension=/path/to/instana.so 。 如果您打算以后再启用扩展，请不要删除它。

2. 如果您有 zzz-instana.ini 文件，也可以按以下方法完全删除该文件：

   $> sudo rm /etc/php/7.0/fpm/conf.d/zzz-instana.ini
   

   在 Windows 中，您可以通过在 powershell 中运行以下命令（以管理员身份）来删除该文件：

   PS C:\> Remove-Item -Path C:\Php\conf\zzz-instana.ini
   

   重要： 请勿删除整个 php.ini 文件。

3. 如果使用预分叉 Worker，则需要重新启动 PHP 主进程。 否则，扩展名将继续保留在内存中。

禁用扩展并不会将其从系统中删除。

删除 PHP 跟踪扩展

PHP 在找不到扩展时会记录启动错误，因此在删除扩展之前，还必须禁用它。 更多信息，请参阅禁用 PHP 跟踪扩展。

PHP 传感器会将 Instana PHP 跟踪扩展放到 extension_dir 设置中指定的目录中， php.ini。 要了解该设置，请运行已启用跟踪的 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 上可访问网络的位置，然后在浏览器中打开该文件，以获取相同的信息。

PHP 传感器只使用第一个值，因此在示例中可以找到扩展名 at/usr/lib/php/20151012。 php.ini或instana.ini中也提供了此扩展的路径。

在 Windows 系统中，您可以在 powershell 中运行以下命令来查找 extension_dir ：

PS C:\> php-cgi -i | Select-String -Pattern 'extension_dir' | ForEach-Object { ($_ -replace '<br\s*/?>', "`n") -replace '<[^>]+>', ' '}
  extension_dir  C:\php\ext  C:\php\ext

要删除扩展名，请运行以下命令：

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

在 Windows 系统中，您可以在 powershell 中（以管理员身份）运行以下命令来删除该文件：

PS C:\> Remove-Item -Path C:\Php\ext\instana.dll

如果您使用的是预分叉 Worker，并且在禁用扩展时没有重启 PHP 主进程，则需要现在重启才能使更改生效。

Instana 用户界面中没有 PHP 痕迹

重要： 确保使用受支持的 PHP 版本。 有关详细信息，请参阅支持的 PHP 版本。

如果使用 Plesk，则需要运行 plesk bin php_handler --reread。

如果在 PHP 应用程序的 Instana UI 中看不到任何痕迹，请完成以下步骤：

1. 验证以下前提条件：

   • PHP 传感器已启用。 有关详细信息，请参阅禁用 PHP 跟踪传感器。
   • PHP 跟踪扩展二进制文件可用。 有关详细信息，请参阅删除 PHP 跟踪扩展。
   • 在代理配置文件中启用了 PHP 跟踪扩展。 更多信息，请参阅禁用 PHP 跟踪扩展。

2. 重新加载 PHP 跟踪扩展，方法是在运行 PHP 应用程序的服务上运行以下 reload 命令重新加载 PHP 跟踪扩展：

   • 供 Apache ：

     systemctl reload apache2
     

   • 对于 PHP-FPM：

     systemctl reload php<version>-fpm
     

     将 reload 命令中的 <version> 替换为系统中安装的实际版本。

如果在 Instana UI 中仍然看不到任何痕迹，而操作系统默认包含 SELinux 或出于安全目的将其添加到环境中，则 SELinux 可能是造成问题的原因。

PHP Tracer 扩展通过 Unix TCP 套接字 <socket path> 与 PHP 守护进程通信，并通过 TCP/IP 端口 42699 与 Instana 代理通信。 当 SELinux 设置为强制模式时，除非 SELinux 被配置为允许，否则它将阻止 PHP 扩展和守护进程相互通信。

要验证 SELinux 是否是造成该问题的原因，请检查 /var/log/audit/audit.log ，查看 PHP 守护进程是否记录了任何静默拒绝。 或者，您也可以完成以下步骤进行烟雾测试：

1. 暂时禁用 SELinux。
2. 重启 PHP 守护进程。

如果 SELinux 被确定为导致问题的原因，可以使用以下任一选项来解决：

• 配置 SELinux 以允许 PHP Tracer 通信：有了 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 安装的扫描目录中找到名为 zzz-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 跟踪扩展的 PHP 运行时。 因此，其精确位置在很大程度上取决于其配置。 通常的位置包括 /var/log/apache2/error.log （用于 Apache2 ）和 /var/log/php<version>-fpm.log （用于 PHP-FPM）。

手动安装 PHP 跟踪扩展

要手动安装 PHP 跟踪扩展，请完成以下步骤：

1. 下载 Instana PHP 跟踪扩展，如下所示：

   1. 从以下资源库下载 shell 脚本：

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

   2. 运行 shell 脚本下载适合您环境的扩展。 以下命令显示了可用选项：

      ./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 的 shell 脚本。

      • 对于 OpenSSL 版本，请使用 -s ssl1 选项下载支持 OpenSSL 1.1 的扩展，或使用 -s ssl3 下载支持 OpenSSL 3.x 的扩展。

      • 对于 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