前言为什么需要全链路监控在分布式系统中一个用户请求可能穿越 Struts2 控制器、Spring 服务、Hibernate 数据访问等多个层级传统日志排查方式面临三大痛点故障定位难无法快速追踪请求流经路径问题排查耗时久某银行案例显示未接入 APM 时异常定位需 45 分钟性能瓶颈隐蔽缺乏各组件耗时统计难以识别慢 SQL、低效方法等瓶颈系统行为不透明微服务调用链路复杂无法直观掌握系统运行状态。而 Webfunny APM 结合 OpenTelemetry 可完美解决这些问题 —— 无需大规模改造 SSH 老项目即可实现零侵入 / 低侵入的全链路追踪。本文将详细拆解对接过程从环境配置到验证落地带你快速上手。Spring、SpringMvc、SpringBoot等java项目类似流程一、项目技术栈与对接核心方案1. 基础技术栈SSH 框架适配版层级技术选型版本核心作用Web 框架Apache Struts26.3.0.2MVC 控制器接收 HTTP 请求容器层Spring Framework5.3.27依赖注入、事务管理ORM 层Hibernate5.6.15.Final数据持久化生成 SQL 执行数据库H2 Database2.2.224开发 / 测试环境内存数据库生产可替换为 MySQL构建工具Maven3.8依赖管理与项目构建运行环境Java11兼容 SSH 框架与 OpenTelemetry Agent链路探针OpenTelemetry Java Agent2.22.0自动采集链路数据无需修改业务代码2. 核心集成架构采用「Agent 自动注入 OTLP 协议上报」方案整体链路如下用户请求 → OpenTelemetry Java Agent自动采集→ SSH 各层级Struts2→Spring→Hibernate→OTLP Exporter → OpenTelemetry Collector → Webfunny APM 平台关键优势零侵入Agent 方式无需修改 SSH 业务代码老项目快速适配全覆盖自动采集 HTTP 请求、SQL 执行、方法调用等核心数据标准化基于 OpenTelemetry 协议支持后续对接其他 APM 平台如 Elastic、Datadog。二、详细对接步骤直接抄作业1. 第一步进入Webfunny Apm后端监控页面新建一个java类型的项目2. 第二步添加 Maven 依赖在 pom.xml 中引入 OpenTelemetry 核心依赖用于注解增强和 API 调用dependencies !-- OpenTelemetry API -- dependency groupIdio.opentelemetry/groupId artifactIdopentelemetry-api/artifactId version1.24.0/version /dependency !-- OpenTelemetry 注解支持 -- dependency groupIdio.opentelemetry.instrumentation/groupId artifactIdopentelemetry-instrumentation-annotations/artifactId version1.24.0/version /dependency /dependencies3. 第三步配置 OpenTelemetry Java Agent3.1 下载 Agent 包从 OpenTelemetry 官网 下载 opentelemetry-javaagent.jar版本 2.22.0放置在服务器目录如 /opt/otel/。3.2 编写启动脚本关键配置Webfunny Apm项目设置页拿到应用ID创建 start-with-otel.sh 启动脚本把应用ID等相关Agent 配置参数与应用启动命令适配 Jetty/Tomcat 容器#!/bin/bash # OpenTelemetry 核心配置 # 服务名称Webfunny 平台显示用 OTEL_SERVICE_NAMEPro-sshDemo # 资源属性环境标识、实例ID便于多环境区分 OTEL_RESOURCE_ATTRIBUTESdeployment.environment应用ID,service.instance.id应用ID,service.version2.0 # Webfunny OTLP 上报端点注意原文档中 http://localhost:9013 若解析失败需检查网络连通性 OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:9013 # 传输协议GRPC 性能更优若报错可改为 http/protobuf OTEL_EXPORTER_OTLP_PROTOCOLgrpc # 超时时间 OTEL_EXPORTER_OTLP_TIMEOUT10s # 仅开启 Trace 采集Metrics/Logs 按需启用 OTEL_TRACES_EXPORTERotlp OTEL_METRICS_EXPORTERnone OTEL_LOGS_EXPORTERnone # 全局方法扫描无需注解自动采集指定包下所有方法 OTEL_INSTRUMENTATION_METHODS_INCLUDEcom.yourapp.service.*,com.yourapp.action.*,com.yourapp.dao.* # 排除工具类/配置类减少冗余 Span OTEL_INSTRUMENTATION_METHODS_EXCLUDEcom.yourapp.util.*,com.yourapp.config.* # 应用启动配置 # Agent 路径替换为你的实际路径 OTEL_AGENT_JAR/opt/otel/opentelemetry-javaagent.jar # 端口配置避免冲突 JETTY_PORT8080 # 整合启动参数 export MAVEN_OPTS\ -javaagent:$OTEL_AGENT_JAR \ -Dotel.service.name$OTEL_SERVICE_NAME \ -Dotel.resource.attributes$OTEL_RESOURCE_ATTRIBUTES \ -Dotel.exporter.otlp.endpoint$OTEL_EXPORTER_OTLP_ENDPOINT \ -Dotel.exporter.otlp.protocol$OTEL_EXPORTER_OTLP_PROTOCOL \ -Dotel.exporter.otlp.timeout$OTEL_EXPORTER_OTLP_TIMEOUT \ -Dotel.traces.exporter$OTEL_TRACES_EXPORTER \ -Dotel.metrics.exporter$OTEL_METRICS_EXPORTER \ -Dotel.logs.exporter$OTEL_LOGS_EXPORTER \ -Dotel.instrumentation.methods.include$OTEL_INSTRUMENTATION_METHODS_INCLUDE \ -Dotel.instrumentation.methods.exclude$OTEL_INSTRUMENTATION_METHODS_EXCLUDE # 启动 Jetty 容器若用 Tomcat替换为 catalina.sh start mvn jetty:run -Djetty.http.port$JETTY_PORT4. 第四步链路增强注解 / 全局扫描二选一方案 AWithSpan 注解精准控制生产推荐在关键业务方法上添加注解自定义 Span 名称和类型适用于核心链路监控// Struts2 Action 层Controller Action(/userList) public class UserAction { WithSpan(value UserAction.listUsers, kind SpanKind.SERVER) public String list() { // 业务逻辑... userService.getAllUsers(); return SUCCESS; } } // Spring Service 层 Service public class UserServiceImpl implements UserService { WithSpan(value UserService.queryAllUsers, kind SpanKind.INTERNAL) Override public List() { return userDao.findAll(); } } // Hibernate DAO 层 Repository public class UserDaoImpl implements UserDao { WithSpan(value UserDao.findUserList, kind SpanKind.INTERNAL) Override public List findAll() { return sessionFactory.getCurrentSession().createQuery(from User).list(); } }方案 B全局方法扫描零代码测试 / 快速验证通过启动脚本中的 OTEL_INSTRUMENTATION_METHODS_INCLUDE 配置自动采集指定包下所有方法无需添加注解适合快速验证全链路。# 全局方法扫描无需注解自动采集指定包下所有方法 OTEL_INSTRUMENTATION_METHODS_INCLUDEcom.yourapp.service.*[*];com.yourapp.action.*[*];com.yourapp.dao.*[*] # 新增启动参数 -Dotel.instrumentation.methods.include$OTEL_INSTRUMENTATION_METHODS_INCLUDE \两种方案对比方式适用场景优点缺点WithSpan 注解生产环境、核心链路性能优、Span 命名清晰需少量代码修改全局方法扫描开发 / 测试、快速验证零代码、覆盖全面可能产生冗余 Span三、验证与问题排查1. 本地验证三步法① 启动应用# 赋予脚本执行权限chmod x start-with-otel.sh# 启动应用./start-with-otel.sh② 发送测试请求curl http://localhost:8080/userList③ 验证结果查看应用日志若输出以下内容说明采集成功[otel.javaagent] LoggingSpanExporter - GET /userList : traceIdxxx spanIdxxx SERVER[otel.javaagent] LoggingSpanExporter - UserAction.listUsers : traceIdxxx spanIdxxx INTERNAL[otel.javaagent] LoggingSpanExporter - UserService.queryAllUsers : traceIdxxx spanIdxxx INTERNAL[otel.javaagent] LoggingSpanExporter - SELECT * FROM user : traceIdxxx spanIdxxx CLIENT登录 Webfunny APM 平台在「链路追踪」模块查看完整调用链。快速定位后端bug问题找到后端项目中错误代码位置2. 常见问题排查避坑指南问题现象高频原因解决方案无 Trace 日志输出Agent 未加载成功1. 检查 -javaagent 路径是否正确2. 确保 JDK 版本 ≥ 83. 避免多个 Agent 冲突如 SkyWalking、Arthas有日志但 Webfunny 无数据OTLP 端点不通1. 用 nc -zv staging.webfunny.cn 9013 测试网络连通性2. 若 GRPC 协议报错改为 OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobuf方法扫描未生效包名配置错误1. 包名不要加 java. 前缀2. 多包用逗号分隔如 com.yourapp.service.*,com.yourapp.action.*SQL 语句未采集Hibernate 版本不兼容确保 Hibernate 版本 ≥ 3.3Agent 2.22.0 原生支持 3.3 版本性能下降明显采样率过高添加采样率配置-Dotel.traces.samplerparentbased_traceidratio -Dotel.traces.sampler.arg0.330% 采样率遇到如下问题降级 / 锁定 OpenTelemetry Agent 稳定版本最新版 Agent 反而有兼容性问题建议降级到1.32.0兼容性最好无该 VerifyError# 下载稳定版Agent wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.32.0/opentelemetry-javaagent.jar2.1.不要同时混合「Agent SDK 注解」只用 Agent 零代码埋点就移除所有手动 opentelemetry-sdk、api 依赖只用代码注解埋点就完全去掉-javaagent参数二者绝对不能混用会双重字节码增强必出 VerifyError​​​​​​2.2.版本匹配检查Spring Boot 2.x → 推荐 OTel Agent 1.29~1.35Spring Boot 3.x → 推荐 OTel Agent 2.xJDK 8 避免使用最新 2.x 系列 Agent兼容性极差四、最佳实践与性能优化1. 采样策略优化链路追踪会产生一定数据量合理配置采样率平衡监控效果与性能开发 / 测试环境全采样-Dotel.traces.sampleralways_on生产环境概率采样如 30% 采样率或自适应采样避免高并发场景下的性能开销。2. 链路粒度控制核心链路支付、下单用 WithSpan 注解精准采集保留完整细节非核心链路查询、统计通过全局扫描排除或降低采样率排除工具类、循环调用方法减少冗余 Span。3. 资源属性规范务必配置 deployment.environment环境和 service.instance.id实例 ID便于在 Webfunny 中区分生产 / 测试环境、不同服务器实例快速定位问题节点。4. 冷数据处理Webfunny 支持链路数据归档可在平台配置 TTL 策略如 30 天避免存储资源浪费降低运维成本。五、总结SSH 框架集成 Webfunny APM 的核心优势在于「低侵入、高覆盖」—— 通过 OpenTelemetry Java Agent 实现零代码全链路采集配合 WithSpan 注解精准控制粒度完美适配老项目改造需求。对接后可实现故障定位效率提升 80%从 45 分钟缩短至分钟级全链路可视化直观查看 HTTP→Action→Service→DAO→DB 的完整调用链性能瓶颈量化精准识别慢 SQL、低效方法为优化提供数据支撑。如果你的项目是 SSH 架构且面临故障排查难、性能优化无方向的问题不妨按照本文步骤对接 Webfunny APM让分布式系统的运行状态一目了然。