Nginx探针部署
UniAgent中集成了Nginx探针,支持监控Nginx应用。
兼容性要求
安装探针之前,请确保您的系统满足如下这些条件:
Linux 64位操作系统,满足以下列表条件之一:
- RedHat Enterprise Linux (RHEL) 6.0 或更高版本
- CentOS 6.0 或更高版本
- SuSE Linux 10.0或更高版本
- Debian 6.0 ("lenny") 或更高版本
- Ubuntu 9.10 ("Karmic Koala") 或更高版本
- 任何其他内核版本高于2.6.32,GLIBC版本高于2.12的Linux发行版。
Nginx需要满足以下条件之一:
- Nginx :1.11.5 - 1.26.1
- Openresty :1.13.6 - 1.25.3
- Tengine :2.3.0 - 3.1.0
任何以Nginx或Openresty为基础组件的产品,例如apisix。
以上Nginx版本必须为官方发布版本,如果在官方版本基础上修改过源码,会造成探针无法正常工作。
如果要适配二次开发过的Nginx,必须提供二次开发后的Nginx源码、编译平台类型(目前仅支持x86_64和aarch64 两种,即amd64还是arm64)、编译选项
/path/to/nginx -V
和编译后的Nginx签名信息strings /path/to/nginx | grep 8,4,8
安装
Nginx探针集成在了UniAgent包中,需要以root权限安装。
下载UniAgent安装脚本并以root权限执行。
sudo sh tingyun-uniagent-版本.sh
手工开启Nginx开关。
sudo sed -i -e "s/nginx_enabled.*/nginx_enabled=true/" /opt/tingyun-oneagent/conf/interceptor.conf
重启Nginx服务。
sudo systemctl restart nginx
配置
探针配置文件路径为/opt/tingyun-oneagent/conf/nginx.conf
。
修改探针日志级别:修改
agent_log_level
字段,修改后不需要重启Nginx应用即可生效。捕捉HTTP请求头:修改
capture_header
字段,目前仅支持配置最多一个HTTP头,修改后不需要重启Nginx应用即可生效。修改Nginx应用命名方式:修改
naming_mode
字段,修改后不需要重启Nginx应用即可生效。支持以下几种命名方式:
0 - 按server_name:port命名 1 - 按server_name命名 2 - 按http_host:port命名 3 - 按http_host命名 4 - 按主机IP:port命名 5 - 按主机IP命名
其中:
- server_name指的是Nginx自身配置文件内指定的server名称。
- http_host指的是HTTP请求内的域名,如果没有域名则取访问端的IP地址。
主机IP指的是当前配置文件内的
host_ip
字段的内容,host_ip字段默认为当前主机或Pod的IP地址,也可手工修改为其他想要的内容。⚠️ 当Nginx配置中一个server段server_name指定了多个名称时,例如以下配置:
server { listen 80; server_name www.test.com www1.test.com www2.test.com; root /usr/share/nginx/html; }
探针只能获取到第一个名称,对于上述例子,只能获取到www.test.com, 即当
naming_mode
配置为0时,www.test.com、 www1.test.com、 www2.test.com 3个域名产生的请求均汇总在www.test.com之下如果想将不同的域名拆开,请将
naming_mode
配置为2,请求会按照域名:端口进行命名。
开启Web前端性能分析功能
UniAgent 2.5.4.0及以上版本支持通过Nginx探针自动对html页面嵌入JS探针,采集Web前端性能数据。
开启流程为在 "用户体验" -> "Web" -> "应用" 页面点击 "添加应用" 按钮,录入页面应用名称,嵌码方式选择 "APM注入", 选择Nginx对应的后端应用,点击启用即可。
在以下场景,无法嵌入JS探针:
非浏览器发起的请求,例如Curl、Wget等工具发起的请求,上游应用利用HttpClient发起的请求
后端应用返回给Nginx时内容为压缩时
Content-Type不是text/html格式时
响应状态码不为200时
JS可嵌码位置超过64K时
常见问题
如何查看Nginx探针的日志
UniAgent 2.2.2.0及以下版本,Nginx探针没有独立的日志文件,探针将日志输出到Nginx的error日志内,请确认Nginx的error日志路径位置。
UniAgent 2.3.0.0及以上版本,Nginx探针日志文件位置为
/opt/tingyun-oneagent/logs/agent/nginx.log
。
将 /opt/tingyun-oneagent/conf/nginx.conf
中agent_log_level
日志级别设置为DEBUG可以输出调试级别的日志。更改日志级别开关不需要重启Nginx,等待1分钟后会自动生效。
搜索Nginx日志:
tail -f /path/to/nginx/logs/error.log | grep tingyun
如何确认Nginx探针是否成功加载?
首先请确认UniAgent服务是否正常工作。
sudo systemctl status tingyun-oneagent
UniAgent服务状态应该为Active: active (running) 。
sudo cat /etc/ld.so.preload
内容应该为
/lib64/libinterceptor.so
。确认Nginx探针开关是否开启。
grep nginx_enabled /opt/tingyun-oneagent/conf/interceptor.conf
确认nginx_enabled开关是否为true,如果不为true请修改并重启Nginx。
确认Nginx探针是否加载。
运行命令查看Nginx进程列表:
ps -ef | grep nginx
找到任意一个Nginx的进程id,运行命令:
sudo grep "tingyun" /proc/[pid]/maps
如果存在
agent/nginx_xxx/lib/tingyun_nginx_module
字样,说明Nginx探针加载成功。[tingyun@bogon ~]$ sudo grep "tingyun" /proc/23241/maps 7f0467f02000-7f0467f05000 r-xp 00000000 fd:01 34581021 /opt/tingyun-oneagent/agent/nginx_2.0.0/lib/tingyun_nginx_module-1.13.10-1111111111.so 7f0467f05000-7f0468104000 ---p 00003000 fd:01 34581021 /opt/tingyun-oneagent/agent/nginx_2.0.0/lib/tingyun_nginx_module-1.13.10-1111111111.so 7f0468104000-7f0468105000 rw-p 00002000 fd:01 34581021 /opt/tingyun-oneagent/agent/nginx_2.0.0/lib/tingyun_nginx_module-1.13.10-1111111111.so
如果没有上述内容,说明探针未成功加载,请确认interceptor.conf中
nginx_enabled=true
是否打开。如果开关已打开,可能是Nginx版本或编译选项没有在探针适配范围内,请执行以下命令查看加载日志:
grep nginx /opt/tingyun-oneagent/logs/oneagent/preload.log
并确认Nginx版本:
/path/to/nginx -v
输出应该类似如下内容:
[tingyun@bogon ~]$ nginx -v nginx version: nginx/1.14.1
确认Nginx编译选项:
/path/to/nginx -V
输出应该类似如下内容:
[tingyun@bogon ~]$ nginx -V nginx version: nginx/1.14.1 built by gcc 8.2.1 20180905 (Red Hat 8.2.1-3) (GCC) built with OpenSSL 1.1.1 FIPS 11 Sep 2018 (running with OpenSSL 1.1.1k FIPS 25 Mar 2021) TLS SNI support enabled configure arguments: --prefix=/usr/share/nginx --with-file-aio --with-ipv6 --with-http_ssl_module --with-http_v2_module --with-http_realip_module --with-http_dav_module --with-http_gzip_static_module
确认Nginx签名信息:
strings /path/to/nginx | grep 8,4,8
输出应该类似如下内容:
[tingyun@bogon ~]$ strings /usr/sbin/nginx | grep 8,4,8 8,4,8,0010111111010111001110111111111110
确认是否有崩溃信息。
UniAgent 2.2.2.0及以下版本:
cat /opt/tingyun-oneagent/logs/agent/nginx.log
UniAgent 2.3.0.0及以上版本:
cat /opt/tingyun-oneagent/logs/agent/nginx.crash
如果有内容则说明探针发生了崩溃,请将此文件内容取回。
确认Nginx探针工作情况。
将
/opt/tingyun-oneagent/conf/nginx.conf
中agent_log_level
日志级别设置为DEBUG。更改此开关不需要重启Nginx,等待1分钟后会自动生效。
UniAgent 2.2.2.0及以下版本, 确认nginx的error.log日志路径,查看nginx的error.log日志:
tail -f /path/to/nginx/logs/error.log | grep tingyun
UniAgent 2.3.0.0及以上版本:
tail -f /opt/tingyun-oneagent/logs/agent/nginx.log
如果日志内出现
app name is null
,说明获取应用名失败,探针默认从server name获取应用名,当nginx没有配置server name时,会出现上述现象,此时需要更改/opt/tingyun-oneagent/conf/nginx.conf
中的naming_mode
为2或4。如果日志内出现
create io thread fail
或open socket fail
或connect to daemon fail
或send to daemon fail
说明和collector通信失败。如果日志仅有大量
send cmd to daemon
,说明collector和DC通讯异常,请检查collector配置,查看/opt/tingyun-oneagent/logs/agent/daemon.log日志。如果日志有
recv config
,说明collector和DC通讯正常。如果日志有
recv config: enabled=true
说明探针开关正常。当收到HTTP请求阶段会打印日志
upstream header: X-Tingyun
。在收到后端其他应用探针返回的HTTP头时会打印日志
upstream response: X-Tingyun-Data
。当返回HTTP响应阶段,如果有跨应用标记会打印日志
outbound header: X-Tingyun-Data
。如果请求仅在nginx本地处理,不转发到upstream,探针不会采集此请求的trace,例如nginx的图片文件,会打印日志
request is static
。当发送trace数据时,会打印日志
send trace to daemon
。如果发送trace数据失败,会打印日志
send trace to daemon fail
。