背景：
在分布式系统架构中，全链路监控是定位性能瓶颈、排查系统问题的核心手段。Apache SkyWalking 作为开源 APM（应用性能监控）工具，凭借其无侵入式采集、丰富的插件生态和强大的可视化能力，成为企业级监控方案的首选。本文基于 Struts2+Spring+Hibernate 技术栈，详细讲解 Webfunny Apm如何用SkyWalking Java Agent 来集成配置、验证流程及常见问题解决方案，帮助开发者快速落地全链路监控。
一、项目技术栈说明
本次实战基于以下技术栈构建，确保方案的通用性和可复用性：
|
层级 |
技术 |
版本 |
用途 |
|
Web 框架 |
Apache Struts2 |
6.3.0.2 |
MVC 控制器层，处理 HTTP 请求 |
|
IoC 容器 |
Spring Framework |
5.3.27 |
依赖注入、事务管理、Bean 管理 |
|
ORM 框架 |
Hibernate |
5.6.15.Final |
数据持久化，简化数据库操作 |
|
数据库 |
H2 Database |
2.2.224 |
内存数据库（开发 / 测试环境） |
|
构建工具 |
Maven |
3.8+ |
项目构建、依赖管理、插件集成 |
|
JDK 版本 |
Java |
11 |
运行环境（兼容 8+） |
|
APM 探针 |
SkyWalking Java Agent |
9.5.0 |
无侵入式全链路数据采集 |
二、SkyWalking 集成架构与原理
2.1 集成架构图
SkyWalking 采用「Agent 采集 + OAP 分析 + UI 展示」的经典架构，本次集成无需修改业务代码，通过 Agent 自动插桩实现数据采集：
┌─────────────────────────────────────────────────────────────┐
│ 用户请求 │
└──────────────────────┬──────────────────────────────────────┘
┌──────────────────────▼──────────────────────────────────────┐
│ SkyWalking Java Agent (自动插桩) │
│ (自动采集 HTTP/JDBC/Hibernate/Struts2 等组件数据) │
└──────────────────────┬──────────────────────────────────────┘
┌──────────────────────▼──────────────────────────────────────┐
│ Struts2 Action │
│ (apm-struts2-2.x-plugin 插件支持) │
└──────────────────────┬──────────────────────────────────────┘
┌──────────────────────▼──────────────────────────────────────┐
│ Spring Service │
└──────────────────────┬──────────────────────────────────────┘
┌──────────────────────▼──────────────────────────────────────┐
│ Hibernate DAO │
└──────────────────────┬──────────────────────────────────────┘
┌──────────────────────▼──────────────────────────────────────┐
│ H2 Database │
└──────────────────────┬──────────────────────────────────────┘
┌──────────────────────▼──────────────────────────────────────┐
│ gRPC Reporter (TraceSegmentService) │
└──────────────────────┬──────────────────────────────────────┘
┌──────────────────────▼──────────────────────────────────────┐
│ Webfunny Apm (数据收集与分析) │
└──────────────────────┬──────────────────────────────────────┘
┌──────────────────────▼──────────────────────────────────────┐
│ Webfunny UI (可视化监控面板) │
└─────────────────────────────────────────────────────────────┘
2.2 自动采集的核心组件
SkyWalking Agent 内置丰富插件，针对本次技术栈自动采集以下关键数据，无需手动埋点：
|
组件类型 |
采集内容 |
依赖插件 |
|
HTTP Server (Jetty) |
请求方法、URL、状态码、响应时间、请求参数 |
apm-jetty-server |
|
Struts2 Action |
Action 类名、方法名、执行耗时、异常信息 |
apm-struts2-2.x-plugin |
|
Spring 组件 |
Bean 方法调用链路、参数、返回值、执行时间 |
apm-spring-core、apm-spring-transaction |
|
Hibernate |
SQL 语句、执行时间、表名、参数绑定 |
apm-hibernate |
|
JDBC 操作 |
数据库连接池状态、SQL 执行耗时、结果集大小 |
apm-jdbc |
三、环境配置（推荐配置文件方式）
为了便于多环境复用和配置管理，推荐采用「独立配置文件 + 启动脚本」的方式集成，避免硬编码导致的维护成本。
3.1 配置文件编写（skywalking.properties）
在项目根目录创建 skywalking.properties 文件，集中管理 Agent 配置：
# ==============================================
# SkyWalking Agent 核心配置文件（支持多环境共享）
# ==============================================
# 1. Agent 基础配置
SKYWALKING_AGENT_PATH="/Users/admin/Documents/workspaces/ssh-apm-demo/skywalking-agent"
# 服务名称（SkyWalking UI 中显示的服务名，建议包含项目标识）
SW_AGENT_NAME="Pro-sshDemo-SkyWalking"
# 实例名称（多实例部署时区分不同节点，可自定义）
SW_AGENT_INSTANCE_NAME="apm_20260417_194334_pro"
# 2. Collector 连接配置
# OAP Server 地址（gRPC 默认端口 11800，HTTP 默认 12800，此处为Webfunny Apm自定义端口 9018）
SW_AGENT_COLLECTOR_BACKEND_SERVICES="xxx.webfunny.cn:9018"
# 通信协议（生产环境推荐 grpc，性能优于 http）
SW_AGENT_PROTOCOL="grpc"
# 3. 采样配置（-1 表示全采样，生产环境可根据流量调整为具体数值）
SW_AGENT_SAMPLE_N_PER_3_SECS=-1
# 4. 插件增强配置
# 开启 JDBC SQL 参数追踪（便于排查慢查询）
SW_AGENT_JDBC_TRACE_SQL_PARAMETERS=true
# 5. 日志配置
# 日志级别（调试时用 DEBUG，生产环境用 INFO/WARN）
SW_LOGGING_LEVEL="DEBUG"
# 日志输出目录（默认在 Agent 目录下的 logs 文件夹）
SW_LOGGING_DIR="${SKYWALKING_AGENT_PATH}/logs/"3.2 启动脚本编写（start-with-skywalking.sh）
创建启动脚本，通过 source 加载配置文件，避免重复配置：
#!/bin/bash
# ==============================================
# SkyWalking Agent 启动脚本（Linux/Mac 环境）
# ==============================================
# 1. 加载配置文件（确保脚本与 skywalking.properties 在同一目录）
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
if [ ! -f "$SCRIPT_DIR/skywalking.properties" ]; then
echo "错误：未找到配置文件 skywalking.properties"
exit 1
fi
source "$SCRIPT_DIR/skywalking.properties"
# 2. 构建 MAVEN_OPTS（Agent 启动参数）
export MAVEN_OPTS="\
-javaagent:$SKYWALKING_AGENT_PATH/skywalking-agent.jar \
-Dskywalking.agent.service_name=$SW_AGENT_NAME \
-Dskywalking.agent.instance_name=$SW_AGENT_INSTANCE_NAME \
-Dskywalking.collector.backend_service=$SW_AGENT_COLLECTOR_BACKEND_SERVICES \
-Dskywalking.agent.protocol=$SW_AGENT_PROTOCOL \
-Dskywalking.agent.sample_n_per_3_secs=$SW_AGENT_SAMPLE_N_PER_3_SECS \
-Dskywalking.plugin.jdbc.trace_sql_parameters=$SW_AGENT_JDBC_TRACE_SQL_PARAMETERS \
-Dskywalking.logging.level=$SW_LOGGING_LEVEL \
-Dskywalking.logging.dir=$SW_LOGGING_DIR"
# 3. 启动应用（Jetty 端口 9080，需与 pom.xml 配置一致）
echo "========================================"
echo "SkyWalking Agent 启动参数加载完成"
echo "服务名称：$SW_AGENT_NAME"
echo "OAP 地址：$SW_AGENT_COLLECTOR_BACKEND_SERVICES"
echo "启动端口：9080"
echo "========================================"
mvn jetty:run -Djetty.http.port=90803.3 核心配置参数说明
|
参数 |
作用 |
注意事项 |
|
SW_AGENT_NAME |
定义服务在 Webfunny Apm中的唯一标识 |
多项目部署时名称不可重复 |
|
SW_AGENT_COLLECTOR_BACKEND_SERVICES |
指定 Webfunny Apm 上报地址和端口 |
确保网络可达（防火墙 / 安全组放行端口） |
|
SW_AGENT_PROTOCOL |
通信协议选择 |
生产环境优先 grpc（性能优化更好） |
|
SW_AGENT_SAMPLE_N_PER_3_SECS |
采样率控制 |
高流量场景建议设置为 100-500，避免数据量过大 |
|
SW_AGENT_JDBC_TRACE_SQL_PARAMETERS |
开启 SQL 参数追踪 |
生产环境可关闭，避免敏感数据泄露 |
3.4 脚本权限配置
给启动脚本添加执行权限（Linux/Mac 环境）：
chmod +x start-with-skywalking.sh四、常见问题与解决方案（实战踩坑）
集成过程中难免遇到各类问题，以下是本次实战中遇到的高频问题及根治方案，覆盖配置、网络、版本等核心场景。
4.1 插件未加载导致无链路数据（最常见）
问题现象
- 应用正常启动，但 Webfunny Apm 中看不到任何 Trace 数据
- Agent 日志显示：no plugin files (skywalking-plugin.def) found
- 仅能看到 JVM 指标，无业务链路数据
错误日志
INFO PluginBootstrap : no plugin files (skywalking-plugin.def) found, continue to start application.根因分析
错误配置了 SW_AGENT_PLUGIN_MOUNT=true，该参数会覆盖 Agent 默认的插件加载路径（plugins 和 activations 目录），导致所有业务插件未加载。
解决方案
删除或注释掉配置文件中的 SW_AGENT_PLUGIN_MOUNT=true 配置，使用 Agent 默认插件路径：
# 错误配置（必须删除/注释）
# SW_AGENT_PLUGIN_MOUNT=true验证方法
启动日志中出现以下信息，说明插件加载成功：
INFO PluginResourcesResolver : find skywalking plugin define in jar:.../apm-struts2-2.x-plugin-9.5.0.jar!/skywalking-plugin.def
DEBUG PluginBootstrap : loading plugin class org.apache.skywalking.apm.plugin.struts2.define.Struts2Instrumentation4.2 版本不兼容导致 gRPC 接口未实现
问题现象
日志中频繁出现 UNIMPLEMENTED 错误：
ERROR ServiceAndEndpointRegisterClient : ServiceAndEndpointRegisterClient execute fail.
org.apache.skywalking.apm.dependencies.io.grpc.StatusRuntimeException: UNIMPLEMENTED: The server does not implement the method /Register/doServiceRegister根因分析
SkyWalking Agent 与 OAP Server 版本不匹配，gRPC 协议不兼容（如 6.x Agent 对接 8.x+ OAP，或 9.x Agent 对接 7.x OAP）。
解决方案
- 确认 OAP Server 版本（通过 UI 或运维查询）
- 下载对应版本的 Agent（推荐 Agent 与 OAP 版本一致或相差不超过 1 个大版本）
- 本次实战使用 Agent 9.5.0，建议 OAP Server 版本为 9.x
4.3 端口冲突导致启动失败
问题现象
Failed to bind to 0.0.0.0/0.0.0.0:8080: Address already in use根因分析
pom.xml 中 Jetty 端口硬编码为 8080，但启动脚本指定为 9080，端口不一致导致冲突。
解决方案
修改 pom.xml 中的 Jetty 插件配置，保持端口一致：
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId>
<configuration>
<httpConnector>
<port>9080</port> <!-- 修改为实际使用的端口 -->
</httpConnector>
</configuration>
</plugin>4.4 部分高级功能不支持（可忽略）
问题现象
日志中出现 UNIMPLEMENTED 错误，但不影响基础链路追踪：
ERROR ConfigurationDiscoveryService : ConfigurationDiscoveryService execute fail.
org.apache.skywalking.apm.dependencies.io.grpc.StatusRuntimeException: UNIMPLEMENTED根因分析
OAP Server 未启用动态配置、Profiling 等高级功能模块，Agent 上报相关数据时被拒绝。
影响范围
- ✅ 正常工作：基础链路追踪、服务拓扑、JVM 指标、SQL 监控
- ❌ 受影响：动态配置、性能分析、事件上报等高级功能
解决方案
无需处理，基础监控功能不受影响，若需使用高级功能，需在 OAP 中启用对应模块。
4.5 网络不通导致数据上报失败
问题现象
Agent 日志显示连接超时，UI 无数据：
ERROR TraceSegmentServiceClient : Send trace segment to collector fail.
java.net.ConnectException: Connection timed out根因分析
- OAP Server 端口未对外开放（防火墙 / 安全组未放行）
- 网络不可达（如跨网段、VPN 未连接）
- OAP Server 未启动
解决方案
- 本地 telnet 验证端口可达：telent xxx.webfunny.cn 9018
- 让运维放行对应端口（gRPC 协议默认 11800，自定义端口需单独配置）
- 确认 OAP Server 正常运行
五、集成验证流程
集成完成后，通过以下步骤验证监控是否生效，确保全链路数据正常采集。
5.1 本地验证步骤
- 启动应用
./start-with-skywalking.sh- 发送测试请求
调用业务接口，触发链路数据采集：
curl http://localhost:9080/userList- 检查 Agent 日志
查看链路数据上报情况：
tail -100 skywalking-agent/logs/skywalking-api.log | grep "TraceSegment"正常输出（表示数据已上报）：
DEBUG TraceSegmentServiceClient : 6 trace segments have been sent to collector.- 查看 Webfunny Apm里面的「链路追踪」「服务拓扑」「SQL 监控」等模块，确认数据正常显示
5.2 日志关键词快速排查
通过 Agent 日志关键词快速判断集成状态：
|
关键词 |
含义 |
正常表现 |
|
PluginResourcesResolver |
插件发现 |
找到 Struts2、JDBC 等插件的配置文件 |
|
PluginBootstrap |
插件加载 |
加载各类插件的 Instrumentation 类 |
|
TraceSegmentService |
链路数据上报 |
显示 X trace segments have been sent |
|
JVMMetricReportService |
JVM 指标上报 |
显示 grpc-status: 0（0 表示成功） |
|
gRPC Reporter |
通信状态 |
无连接超时、拒绝等错误 |
六、生产环境注意事项
- 配置优化
-
- 日志级别调整为 INFO 或 WARN，避免 DEBUG 日志占用过多磁盘
-
- 采样率根据流量调整（如每秒 100 条请求，设置 SW_AGENT_SAMPLE_N_PER_3_SECS=300）
-
- 关闭敏感数据采集（如 SW_AGENT_JDBC_TRACE_SQL_PARAMETERS=false）
- 版本管理
-
- 保持 Agent 与 OAP Server 版本一致，避免协议不兼容问题
-
- 定期更新 Agent 版本，修复已知漏洞和性能问题
- 网络稳定性
-
- 生产环境建议 Agent 与 OAP Server 部署在同一网段，降低网络延迟
-
- 启用 gRPC 协议的重连机制（Agent 内置，无需额外配置）
- 资源监控
-
- 监控 Agent 占用的 CPU / 内存（通常较低，约 1-5% 开销）
-
- 定期清理 Agent 日志，避免磁盘占满
七、总结
本文基于 Struts2+Spring+Hibernate 技术栈，详细讲解了 SkyWalking Java Agent 的无侵入式集成方案，核心亮点如下：
- 配置集中化：通过独立配置文件管理 Agent 参数，支持多环境复用，降低维护成本；
- 问题全覆盖：针对插件加载、版本兼容、端口冲突等高频问题，提供可直接落地的解决方案；
- 验证流程化：通过「启动 → 请求 → 日志 → UI」四步验证，确保集成生效；
- 生产可用：提供生产环境优化建议，兼顾监控效果和系统性能。
Webfunny Apm作为一款成熟的 APM 工具，能够帮助团队快速定位分布式系统中的性能瓶颈和异常问题，建议在生产环境中全面推广。如果在集成过程中遇到其他问题.
