## 官网地址 https://business.swoole.com/ ## 客服微信 一般的使用问题，你可以在我们完整的[用户手册](http://wiki.tracker.swoole-cloud.com)中找到答案。 如果遇到疑难问题和使用故障，您可以联系客服微信咨询。 

实时统计客户端机器的`CPU`、`内存`、`磁盘`、`网络`使用状况 ### CPU  ### 内存  ### 磁盘  ### 网络 

在线控制 Agent 的部分功能，如修改探针状态、修改采样率、修改获取调用栈以及对应的客户端信息、状态等  ## 探针状态 远程开启关闭探针，`1`表示开启，`0`表示关闭 ## 调用栈 链路追踪中的 trace 信息增加了一个调用栈，会展示该请求中抓取到的相关操作的调用方法、行号、扩展信息、文件，如下图  可以进行开启或关闭，修改对应调用栈深度，`0`表示关闭 ## 采样率 远程动态修改采样率。采样率只作用于应用追踪，设置为`100`则表示每次请求都会生成一条 trace 数据

[TOC] ## 进程列表 统计客户端fpm和cli的pid，可进行远程调试、查看调用栈以及进程CPU和内存占用统计  ## 远程调试 对于以下四种工具，可以直接在服务端点击按钮远程开启后进行调试，无需修改代码，重启服务。开启后发生请求，日志自动上传服务端后台进行分析展示 >[danger] 对性能有所影响，开启调试完毕后请及时关闭。 ### 阻塞检测 可详细看到阻塞的堆栈信息，执行耗时，系统调用信息  ### 内存泄漏 >[danger] ⚠️此功能仅支持 PHP71+ 版本，即PHP71、PHP72、PHP73 会获取到存在内存泄漏的文件堆栈信息，说明你需要在代码逻辑执行完毕后将该键名 `unset` 掉，就可以解决内存泄漏问题  ### 性能分析 性能分析可以生成分层分析表、调用图和火焰图，都可以直观的找到对应的瓶颈所在  #### 分层分析表  #### 调用图  #### 火焰图  ### 查看调用栈 >[danger] 此功能目前只限付费用户使用 方便定位 PHP 卡死问题，包括但不限于`死循环`、`sesstion_start函数导致卡死`、`flock函数导致卡死`、`TCP超时时间为-1`、`swoole协程的lock`等。  **开启并且发生请求后**就会上报，可以在「调用栈页面」查看，如果页面没有数据则可能数据未上报、未发生卡死问题等

Tracker的调试工具链目前有4种，分别是`性能分析`、`阻塞检测`、`内存泄漏`、`查看当前调用栈`。 经常有人问它们的适用场景以及区别，在此予以说明： ## 内存泄漏 是用在 Swoole、Workerman 等常驻进程模式下的工具，在 FPM 下是不存在内存泄漏一说的，它能帮助你检查这种情况： 在请求开始后向某一个全局变量（`$GLOBALS`或者类的静态属性等）追加内容，并且在请求结束的时候追加在全局变量的内容没有被`unset`掉，那么就认为有内存泄漏。 >[info] 请求开始和请求结束可以通过调用`Tracker API`来指定，具体参考「[调试器](debuger.md)」章节`手动埋点调试`。 ## 阻塞检测 阻塞检测工具的准确的来说应该叫做`阻塞系统调用检测工具`，它的原理是拦截进程的所有系统调用，在开始和结束打点取时间差，如果大于配置的时间（默认`10ms`）就把当前的 PHP 调用堆栈上报到 Tracker 的后台，可以方便的定位到调用栈阻塞在哪个系统调用，耗时多少毫秒，通过具体的系统调用我们能判断出进程是锁等待、还是磁盘 IO 问题、网络 IO 问题等。 但是这个工具无法检测出卡死的问题，具体可以参考微课程的这篇文章[教你秒级定位PHP卡死问题](https://course.swoole-cloud.com/article/2) ## 查看当前调用栈 对于阻塞检测工具无法发现的卡死问题，需要用`查看当前调用栈`工具来定位到底卡死在哪个 PHP 函数了，调用堆栈是什么。 ## 性能分析 是最直观的一种性能分析方式，因为他可以生成一整张的调用图，他的原理是拦截所有的 PHP 函数调用，并且在开始和结束打点取时间差。 它是非常好的`定位hot函数`的工具，方便的定位到最耗时的函数是哪个，但是无法看到调用栈，也不知道具体的系统调用，每次调用的耗时也不知道。 ## 到底该用哪个工具 一般性能调优的话用`性能分析`工具就够用，生产环境突然产生了性能问题最先用性能分析查看，先大概定位问题，如果请求阻塞非常久（也就是卡死）可以直接用`查看当前调用栈`工具查看，如果请求只是变慢了就用`阻塞检测工具`。 当然也可以挨个使用一遍，多维度发现问题。

链路追踪生成`Trace信息`，在发生请求后，这里会优先展示链路信息。 >[danger] 如果采样率为百分百时，发现前几次的请求不会被抓取到，这是因为客户端会获取相关应用ID等信息并生成缓存； 按天查询单个接口的`调用时间`、`耗时时长`及`完整的Trace信息`，快速定位耗时较长的调用。   可配合调试工具进行链路调试  ## 调用栈 在 [Agent列表](agent-list.md) 中开启 PHP调用栈，会增加一个调用栈列表，会展示该条 trace 中的一些调用信息

目前服务端调用统计展示有5分钟延时，需要进行数据分析汇总统计。**可先查看链路追踪** 1. 监控对应应用的接口在`某段时间内`的`调用次数`、`成功次数`、`失败次数`、`成功率`、`响应最大值`、`响应最小值`、`平均响应时间`等数据 2. 接口调用的`历史数据对比` 3. 接口的`主调明细`和`被调明细`统计    

首页根据应用管理里配置的阈值查看该项目下所有应用的整体运行概况 ## 响应时间、请求次数  ## 失败率、请求类型平均响应  ## 慢请求追踪、接口调用  ## 请求类型汇总  ## 实例调用关系拓扑图 

## 加载扩展后报错 undefined symbol: php_pdo_get_exception 扩展需要放在pdo扩展后面加载。使用`php --ini | grep "Scan for additional .ini files in:"`查看第三方加载目录，在此目录中创建一个`swoole_tracker`的配置  ## 加载扩展后报错`undefined symbol: compiler_globals in Unknown` 扩展只支持 `NTS` 非线程安全版本 PHP，可使用命令`php -v`查看  ## 加载扩展后报错`undefined symbol: _zval_ptr_dtor in Unknown` 下载的`swoole_tracker.so`与机器的`PHP`版本不一致，请确保下载了正确的扩展。

**1. 一切问题先检查客户端、`swoole_tracker`扩展、服务端版本是否一致，是否为最新发布版本； 2. 客户端Agent服务是否启动； 3. 安装扩展完成以后是否重启客户端 Server 服务或 php-fpm 服务；** >[success] swoole_tracker扩展的发布版本可能会出现比客户端、服务端高，这个不影响。 * 查看客户端版本 `ps -ef | grep agent`  * 查看 `swoole_tracker` 扩展版本 ```ini ;php.ini不要忘了添加 extension=swoole_tracker.so apm.enable=1 apm.sampling_rate=100 ``` >[info] cli模式 php --ri swoole_tracker  >[success] fpm模式 phpinfo()  * 查看服务端版本  [TOC] ## 1. 找不到对应应用 * 查看项目是否正确，自动创建的应用会放到默认项目中 * 检查该应用是否存在合并应用或应用黑名单中 * 检查客户端`swoole_tracker` 配置是否正确，参考安装客户端->安装扩展 * 检查客户端是否给该服务端上报 ## 2. 调用统计/链路追踪无信息 * 检查对应后台地址(IP或域名)是否正确，防火墙、安全组中端口是否开放 >[danger] 端口在配置文件`/opt/swoole/config/config_port.conf`中 * 检查客户端进程是否存在 * 检查客户端`swoole_tracker`配置是否正确，参考安装客户端->安装扩展 * 存在脏数据缓存，等待5-10分钟（之前逻辑为客户端上报的时候会创建文件缓存，每五分钟删除一次，重新安装服务端后客户端文件缓存未删除，出现脏数据缓存，导致短时间内无法上报，现已将缓存写入内存中，重装服务端后**重启服务端fpm和重启swoole-admin服务就能正常接收数据**，无需等待） * 检查采样率`apm.sampling_rate` ## 3. Service应用无调用统计、链路追踪信息 * 检查代码使用是否正确，参考上报数据 * 检查客户端服务名和服务端创建是否一致 * 同问题2 ------ >[danger] 如果以上2，3两个问题，所有步骤尝试过后都无效，请点击swoole-admin后台的**首页**、**应用监控**和**应用追踪**，查看是否有弹窗提醒，没有请[咨询客服](contact-us.md) ## 4. 管理NodeAgent守护进程 目前NodeAgent采用系统的守护进程管理，如果要管理NodeAgent的状态： * 对于采用openrc和类似sysvinit的系统（如Debian 7 "Wheezy", Ubuntu 14.04 "Trusty"（默认不安装systemd）, CentOS(RHEL) 6, Fedora 14, Gentoo（可选）, Archlinux（可选）, Alpine Linux）使用命令 ```bash /etc/init.d/node-agent start /etc/init.d/node-agent stop /etc/init.d/node-agent restart ``` 来启动/停止/重启NodeAgent（非root用户需要sudo） * 对于采用systemd的系统（Debian 8 "Jessie"及以后, Ubuntu 15.04 "Vivid"及以后, CentOS(RHEL) 7及以后, Fedora 15及以后, Gentoo（可选）, Archlinux（可选））使用命令 ```bash systemctl start node-agent systemctl stop node-agent systemctl restart node-agent ``` 来启动/停止/重启NodeAgent（非root用户需要sudo） ## 5. 增加调试器中的相关代码后报错：Fatal error: Uncaught Exception: plz set apm.enable_memcheck=1 which in php.ini 解决方法：在 `php.ini` 中添加配置： `apm.enable_memcheck=1` >[info] 从2.3.3版本以后默认关闭调试功能，需要手动进行配置。或者使用远程调试 ## 6. 重装服务端并清空数据库后，没有上报信息等情况 从2.3.3版本开始有部分信息缓存在php内存中，服务端重装后，数据对应不上导致部分数据获取失败，所以客户端需要重启fpm进程 ## 7. 机器信息无上报信息 1. 检查网络是否通畅 2. 查看客户端日志 `/opt/swoole/logs/NodeAgent-sysinfoerr.log` 是否存在，存在查看内容，是否有上报失败字样 3. 服务端地址是否正确 ## 8. 进程列表无信息 1. 查看客户端node-agent进程是否存在 2. 查看客户端本地是否有pid文件，路径：`/var/run/swoole_tracker/`下的cli和fpm文件夹中 3. pid文件对应的进程是否正常 ## 9. 加载扩展后报错 [扩展安装问题](扩展安装问题.md) ## 11. 客户端运行报错 sw_get_entrypoint()：ERROR：mkdir error, make sure that start the agent first (Premission denied). 请使用 root 用户启动 Agent服务，没有启动 Agent 服务并且不是使用 root 用户启动时会报这个错误 ## 12. 报错：PHP Startup: apm.enable and apm.enable_malloc_hook can't be turned on together, reset apm.enable=0 开启了`apm.enable_malloc_hook =1`之后其他的功能均不可用，只能进行内存泄漏检测。

[TOC] ## 项目 在整个系统中，可以分为多个项目，比如默认项目、基础项目等等，用来区分不同类型，不同层次的项目。 系统中的默认项目为所有自动创建的 `Web` 应用都会默认在此项目中，可以移动到其他项目中。 ## 应用 应用分为两种类型，一种`Web`应用， 一种`Service`应用。 ### 应用图标说明  正方形表示自动创建应用 圆形表示手动添加应用  蓝色(#1F6FB5)表示 `WEB` 应用 橙黄色(#FCD692)表示 `Service` 应用 ## 主调、被调 主调与被调是主动与被动的关系。 现在有A、B两个函数，A函数调用了B函数，那么，A函数就是主调函数，B函数就是被调函数。 主调明细和被调明细也是如此，谁主动调用，谁被调用。 这和现实生活中的打电话是一样的，一个是主叫，一个是被叫。

[TOC] >[success] 上报成功后在后台查看，需要切换当前项目，默认在默认项目中。  >[danger] 可以先查看链路追踪，首页和调用统计需要时间进行分析。 ## php-fpm模式 如果你只使用的php-fpm模式，那么到此为止服务端后台应该在发生请求后已经有数据了 fpm下会自动创建应用，名称为域名或对应ip，可以登录服务端后台查看应用追踪等数据 ## 常驻进程Service模式 ### 自动创建 系统支持自动生成应用名称并创建应用，无需修改任何代码。 如果使用 `Swoole` 的 `HttpServer` 那么生成的应用名称为`ip:port` 如果使用 `Swoole` 其他的 `Server` 那么生成的应用名称为`ip(hostname):port` 查看对应的应用信息即可。

>[danger] Swoole Tracker 目前仅支持 Linux 系统，不支持Unix、Windows、Mac OS；不支持ARM架构；支持 PHP5.4、5.5、5.6、7.0、7.1、7.2、7.3、7.4、8.0。 [TOC] ## 安装部署 ### 第一步：后台申请 在[官网](https://business.swoole.com/SwooleTracker/catdemo)申请使用后，会看到如下信息 >[success] 安装或更新 步骤相同，更新需要点击重新申请；卸载直接卸载扩展，关闭客户端进程（可参见下文管理客户端进程）。  ### 第二步：安装Agent进程 点击客户端包后的**下载**，会得到一个名为`swoole-tracker-install.sh`的脚本，上传到机器后进行如下操作： >[danger] 如果使用 wget 下载，文件名为注册的手机号，操作和下文相同 ```bash chmod +x swoole-tracker-install.sh ./swoole-tracker-install.sh ``` 执行完成后，会在当前目录下生成`swoole-tracker`文件夹，目录结构如下 ``` . ├── app_deps ├── deploy_env.sh ├── inst.sh ├── musl-compat ├── swoole_tracker54.so #对应各版本的扩展 ├── swoole_tracker55.so ├── swoole_tracker56.so ├── swoole_tracker70.so ├── swoole_tracker71.so ├── swoole_tracker72.so ├── swoole_tracker73.so └── swoole_tracker74.so ``` ### 第三步：安装扩展 根据你的机器PHP版本安装对应的扩展，复制对应的扩展到PHP环境扩展安装目录 >[info] 获取扩展安装目录：php -ini | grep extension 或者php -r "echo @ini_get("extension_dir").PHP_EOL;" ``` cp swoole_tracker70.so /your_php_extensions_path/swoole_tracker.so ``` > [danger] 若扩展安装不上，可使用下载包中的`inst.sh`进行安装，或者联系识沃客服寻求帮助 在 `php.ini` 中加入以下配置 ```ini extension=swoole_tracker.so ;打开总开关 apm.enable=1 ;采样率 例如：100% apm.sampling_rate=100 ;开启内存泄漏检测时添加 默认0 关闭状态 apm.enable_memcheck=1 ``` >[danger] `enable`为 1 时表示调用统计百分百拦截并上报 > `sampling_rate`采样率只作用于链路追踪，设置为 100 则表示每次请求都会生成一条 trace 数据 #### 卸载不兼容扩展 1. xdebug 2. ioncube loader 3. zend guard loader 4. xhprof 5. swoole_loader （加密后的代码不能进行分析） ### 第四步：重启PHP服务 安装完成后，需要**重启对应的 SwooleServer 或者 php-fpm 服务**，发生请求后稍等片刻，等待服务端接收客户端发送的数据。 >[success] 以上操作会在宿主机直接安装，如果你需要在Docker中部署，请看下文 ## 在Docker环境中部署客户端 >[danger] 请注意修改相关路径为你自己的路径！！！以下的swoole.so只是演示说明可安装其他扩展，swoole_tracker不依赖swoole扩展 在docker环境部署需要修改Dockerfile或者docker-compose.yml或者在`docker run`命令中添加参数，以下以采用官方docker-compose v3.7配置文件格式，php:fpm-7.x(-alpine)镜像为例，描述如何在docker部署 ### 修改Dockerfile以部署node-agent 在Dockerfile中执行 `swoole-tracker-install.sh` 来部署node-agent，然后在entrypoint中添加node-agent，例如 ```dockerfile # dockerfile的其他部分 # 部署node-agent ADD swoole-tracker-install.sh /tmp/ RUN chmod +x /tmp/swoole-tracker-install.sh && \ cd /tmp/ && \ ./swoole-tracker-install.sh && \ rm /tmp/swoole-tracker-install.sh # 添加entrypoint脚本 RUN printf '#!/bin/sh\n/opt/swoole/script/php/swoole_php /opt/swoole/node-agent/src/node.php &\nphp-fpm $@' > /opt/swoole/entrypoint.sh && \ chmod 755 /opt/swoole/entrypoint.sh # 启用entrypoint脚本（-x方便调试， 可以去掉） ENTRYPOINT [ "sh", "-x", "/opt/swoole/entrypoint.sh" ] ``` ### 启用扩展 对于官方镜像php:fpm系列，php(-fpm)默认读取/usr/local/etc/php/conf.d下的配置文件，默认的entrypoint会将"-"开头的参数作为fpm启动参数，因此可以采用以下方式启用swoole_tracker扩展 在Dockerfile添加配置文件： ```dockerfile RUN printf 'extension=/path/to/swoole.so\nextension=/path/to/swoole_tracker7x.so\n' > /usr/local/etc/php/conf.d/swoole-tracker.ini ``` 或在docker-compose.yml添加启动参数 ```yml services: your-service: build: context: cgi-docker dockerfile: Dockerfile image: myphpfpm:1 command: - "-dextension=/path/to/swoole.so" - "-dextension=/path/to/swoole_tracker7x.so" ``` 或在docker run命令中添加启动参数 ```bash docker run --other-arguments myphpfpm:1 -dextension=/path/to/swoole.so -dextension=/path/to/swoole_tracker7x.so ``` ### 配置docker安全选项 扩展中使用了默认权限不允许的系统调用，使用了docker默认seccomp配置不允许的系统调用，需要额外配置： 参考https://docs.docker.com/engine/security/seccomp/ 对于权限配置，可以添加SYS_PTRACE cap，或者使用提升权限模式（不推荐） 对于seccomp，可以修改seccomp配置，或关闭seccomp配置（不推荐，这将导致docker内程序可以执行create_module，kexec_load等危险系统调用） ### 修改seccomp配置 修改seccomp配置文件（修改自[默认文件](https://github.com/moby/moby/blob/master/profiles/seccomp/default.json))）: ``` --- a.json +++ b.json # 在.syscalls[0].names中加入"ptrace"，这将允许ptrace @@ -359,7 +359,8 @@ "waitid", "waitpid", "write", - "writev" + "writev", + "ptrace" ], "action": "SCMP_ACT_ALLOW", "args": [], # 如果你的docker较新，则它已经配置了ptrace在4.8以上内核可用 # 参考https://github.com/moby/moby/commit/1124543ca8071074a537a15db251af46a5189907 # 移除这段 @@ -369,18 +370,6 @@ }, - { - "names": [ - "ptrace" - ], - "action": "SCMP_ACT_ALLOW", - "args": null, - "comment": "", - "includes": { - "minKernel": "4.8" - }, - "excludes": {} - }, { "names": [ "personality" ], "action": "SCMP_ACT_ALLOW", ``` 在docker run使用该seccomp并给予SYS_PTRACE权限： ```bash docker run --other-arguments --cap-add=SYS_PTRACE --security-opt seccomp=/path/to/that/modified/profile.json ... ``` 或docker-compose.yml中: ```yml # 在docker-compose.yml中： services: your-service: build: context: cgi-docker dockerfile: Dockerfile image: myphpfpm:1 # 给予SYS_PTRACE权限 cap_add: - "SYS_PTRACE" # 配置使用修改的seccomp security_opt: - "seccomp=/path/to/that/modified/profile.json" ``` ### 关闭seccomp（不推荐） 与修改配置类似，但不需要创建json，将 `seccomp=/path/to/that/modified/profile.json`换成`seccomp=unconfined`即可 ## 管理客户端进程 查看 [常见问题](qa.md) 中的「管理NodeAgent守护进程」