Webfunny Apm + SkyWalking Agent 全链路监控实战：从集成到问题排查

背景：

在分布式系统架构中，全链路监控是定位性能瓶颈、排查系统问题的核心手段。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=9080

3.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.Struts2Instrumentation

4.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 未启动

解决方案

1. 本地 telnet 验证端口可达：telent xxx.webfunny.cn 9018

1. 让运维放行对应端口（gRPC 协议默认 11800，自定义端口需单独配置）

1. 确认 OAP Server 正常运行

五、集成验证流程

集成完成后，通过以下步骤验证监控是否生效，确保全链路数据正常采集。

5.1 本地验证步骤

1. 启动应用

   ./start-with-skywalking.sh

2. 发送测试请求

调用业务接口，触发链路数据采集：

curl http://localhost:9080/userList

1. 检查 Agent 日志

查看链路数据上报情况：

tail -100 skywalking-agent/logs/skywalking-api.log | grep "TraceSegment"

正常输出（表示数据已上报）：

DEBUG TraceSegmentServiceClient : 6 trace segments have been sent to collector.

1. 查看 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 | 通信状态 | 无连接超时、拒绝等错误 |

六、生产环境注意事项

1. 配置优化

• • 日志级别调整为 INFO 或 WARN，避免 DEBUG 日志占用过多磁盘

• • 采样率根据流量调整（如每秒 100 条请求，设置 SW_AGENT_SAMPLE_N_PER_3_SECS=300）

• • 关闭敏感数据采集（如 SW_AGENT_JDBC_TRACE_SQL_PARAMETERS=false）

1. 版本管理

• • 保持 Agent 与 OAP Server 版本一致，避免协议不兼容问题

• • 定期更新 Agent 版本，修复已知漏洞和性能问题

1. 网络稳定性

• • 生产环境建议 Agent 与 OAP Server 部署在同一网段，降低网络延迟

• • 启用 gRPC 协议的重连机制（Agent 内置，无需额外配置）

1. 资源监控

• • 监控 Agent 占用的 CPU / 内存（通常较低，约 1-5% 开销）

• • 定期清理 Agent 日志，避免磁盘占满

七、总结

本文基于 Struts2+Spring+Hibernate 技术栈，详细讲解了 SkyWalking Java Agent 的无侵入式集成方案，核心亮点如下：

1. 配置集中化：通过独立配置文件管理 Agent 参数，支持多环境复用，降低维护成本；

1. 问题全覆盖：针对插件加载、版本兼容、端口冲突等高频问题，提供可直接落地的解决方案；

1. 验证流程化：通过「启动 → 请求 → 日志 → UI」四步验证，确保集成生效；

1. 生产可用：提供生产环境优化建议，兼顾监控效果和系统性能。

Webfunny Apm作为一款成熟的 APM 工具，能够帮助团队快速定位分布式系统中的性能瓶颈和异常问题，建议在生产环境中全面推广。如果在集成过程中遇到其他问题.