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

简简单单就是我_hehe2026-05-11 10:02

背景：

在分布式系统架构中，全链路监控是定位性能瓶颈、排查系统问题的核心手段。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 工具，能够帮助团队快速定位分布式系统中的性能瓶颈和异常问题，建议在生产环境中全面推广。如果在集成过程中遇到其他问题.

相关推荐
摇滚侠5 天前
Skywalking 应用性能监控和可观测性分析平台 简介
skywalking
Databuff6 天前
skywalking 快速使用入门
skywalking
摇滚侠8 天前
Apache Skywalking 实战 阅读笔记 第三章
笔记·apache·skywalking
摇滚侠9 天前
Apache Skywalking 实战 阅读笔记 第二章
笔记·apache·skywalking
Databuff9 天前
国产开源APM databuff 成为 CNCF 顶级项目opentelemetry 官宣Vendor
运维·开源·skywalking·apm·可观测性·opentelemetry
摇滚侠9 天前
Skywalking 全套教程 环境搭建 01-05
skywalking
摇滚侠10 天前
Apache Skywalking 实战 阅读笔记 第一章
笔记·apache·skywalking
就改了1 个月前
Windows 环境 SkyWalking 完整实操教程
windows·微服务·skywalking
Jul1en_1 个月前
【SpringCloud】SkyWalking 链路追踪知识详解及部署教程
java·后端·spring·spring cloud·skywalking
SRETalk1 个月前
SkyWalking / Jaeger / ARMS 已经有了，还需要统一可观测平台吗
skywalking·apm·jaeger·flashcat·arms
热门推荐
01GitHub 镜像站点02幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南03AI科技热点日报 | 2026年07月01日042026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片05GPT-5.5 对比 GPT-5.6 Sol、Terra、Luna：官方性能数据与选型分析062026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf092026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？10几个好用的ip纯净度检测网站