简介本资源是一个面向Java后端开发者与微服务监控初学者的Spring Boot集成SkyWalking实战演示项目聚焦分布式链路追踪核心能力落地解决微服务架构下请求链路不可见、性能瓶颈难定位等典型问题。压缩包共13个文件含2个核心Java启动类展示Agent探针接入与手动埋点、2份Markdown文档HELP.md与README.md详解部署步骤与概念说明、6张关键界面截图涵盖SkyWalking UI中的Trace查询、Span详情、拓扑图及告警配置以及pom.xml、application.properties和LICENSE等必要配置与合规文件整体仅537KB轻量易导入。已有189人学习下载。读者可直接运行项目观察完整调用链生成过程深入理解Trace生命周期、Span嵌套关系、Tag标注与Log打点等核心机制并获得一套可复用的SkyWalking集成模板与可视化验证路径。1. 项目概述与核心价值最近在整理技术资产时翻出了一个几年前做的“基于Spring Boot的SkyWalking演示项目”。这个压缩包躺在硬盘角落里本以为是个简单的Demo重新打开梳理后发现里面浓缩了不少当时在微服务可观测性实践上的思考和踩过的坑。对于现在很多团队来说链路追踪不再是“要不要做”的问题而是“怎么做才能更高效、更深入”的问题。SkyWalking作为APM领域的佼佼者其与Spring Boot的集成看似简单但真想让它发挥出最大价值从探针埋点、数据采集到问题诊断每一步都有不少门道。这个演示项目就是一个完整的、可运行的“样板间”。它不仅仅展示了如何把SkyWalking的Agent挂到Spring Boot应用上更关键的是它模拟了真实业务场景中常见的几种链路情况数据库操作、HTTP客户端调用、异步任务处理并预设了一些典型的“问题”链路比如慢SQL、异常抛出等。通过这个项目你可以快速搭建一个本地可观测性环境亲眼看到一次用户请求背后究竟经过了哪些服务、调用了哪些资源、耗时卡在了哪里。这对于开发者在日常开发中提前发现性能瓶颈或是运维同学在故障排查时快速定位根因都有着直接的帮助。2. 项目整体设计与思路拆解2.1 技术栈选型与架构意图这个演示项目的核心是Spring Boot 2.x具体版本为2.7.18这是一个长期支持版本兼顾了稳定性和现代特性搭配SkyWalking 8.x的Java Agent进行无侵入式的链路追踪。选择这个组合背后有明确的考量。首先Spring Boot的自动配置和起步依赖特性使得构建一个包含Web、JPA、Redis、异步处理等组件的应用变得极其简单这正好为我们模拟复杂的微服务内部调用链提供了便利。我们可以在一个应用内通过不同的Controller和Service模拟出跨模块、跨中间件的调用场景。其次SkyWalking的Java Agent采用字节码增强技术无需修改业务代码即可实现追踪。这对于演示和入门来说至关重要它降低了可观测性接入的门槛。项目的设计意图不是教你如何写SkyWalking的插件而是让你先直观地理解在标准的技术栈下SkyWalking能自动捕捉到什么以及你该如何配置和查看这些信息。整个项目的架构思路是“单体模拟微服务”。即在一个Spring Boot应用中创建多个功能模块user-service: 模拟用户服务处理用户相关请求。order-service: 模拟订单服务调用user-service和product-service。product-service: 模拟商品服务包含数据库操作。共用组件集成Redis缓存、异步Async任务、RestTemplate和Feign两种HTTP客户端调用方式。这样一次访问订单查询接口的请求就会在应用内部形成一个模拟的“微服务”调用链并被SkyWalking完整记录。2.2 SkyWalking Agent集成模式解析集成SkyWalking主要有两种模式Agent模式和SDK模式。这个演示项目坚定地采用了Agent模式这是生产环境最常见、也是最推荐的方式。Agent模式的原理是在JVM启动时通过-javaagent参数挂载SkyWalking的代理包skywalking-agent.jar。这个代理会在类加载时对特定的类如Spring MVC的DispatcherServlet、JDBC的Statement、HttpClient的组件等进行字节码增强植入追踪逻辑。它的最大优势是无侵入性。你的业务代码不需要引入任何SkyWalking的依赖也不需要写任何追踪相关的代码。这对遗留系统改造和保持代码纯净度非常友好。SDK模式则需要你在项目中显式引入SkyWalking的客户端依赖如apm-toolkit-trace并在代码中手动埋点。这种方式更灵活可以自定义追踪粒度但增加了代码复杂度和耦合度。注意对于绝大多数Spring Boot项目尤其是希望快速获得可观测能力的情况首选Agent模式。除非你有非常定制化的追踪需求否则不要轻易引入SDK那会让你的代码变得“臃肿”。演示项目中skywalking-agent目录已经包含了所需的基础Agent文件。你需要做的只是在启动应用时通过JVM参数指定Agent的路径和配置。这种设计让你能清晰地分离“业务代码”和“观测配置”符合现代运维理念。3. 环境准备与项目启动3.1 基础设施部署SkyWalking后端SkyWalking的架构分为三部分Agent探针集成在应用中、OAP Server后端负责处理数据、UI前端用于数据展示。要运行演示项目首先需要启动OAP Server和UI。最快捷的方式是使用Docker Compose。我在项目根目录下准备了一个docker-compose.yml文件内容精简如下version: 3.8 services: oap: image: apache/skywalking-oap-server:8.16.0-es7 container_name: sw-oap restart: always ports: - 11800:11800 # gRPC端口Agent上报数据 - 12800:12800 # HTTP端口UI连接 environment: SW_STORAGE: elasticsearch7 SW_STORAGE_ES_CLUSTER_NODES: elasticsearch:9200 ui: image: apache/skywalking-ui:8.16.0 container_name: sw-ui restart: always ports: - 8080:8080 environment: SW_OAP_ADDRESS: oap:12800 depends_on: - oap elasticsearch: image: elasticsearch:7.17.6 container_name: sw-es restart: always environment: - discovery.typesingle-node - ES_JAVA_OPTS-Xms512m -Xmx512m - xpack.security.enabledfalse ports: - 9200:9200 - 9300:9300 ulimits: memlock: soft: -1 hard: -1启动命令非常简单cd /path/to/your/project docker-compose up -d等待片刻后访问http://localhost:8080即可看到SkyWalking UI界面。OAP Server使用Elasticsearch 7作为存储这是目前比较稳定和流行的搭配。3.2 演示项目配置与启动解压基于Spring Boot的SkyWalking演示项目.zip后你会看到一个标准的Maven项目结构。核心配置在于应用启动参数。编译项目在项目根目录下执行mvn clean package -DskipTests生成可执行的JAR包通常位于target/demo-application-0.0.1-SNAPSHOT.jar。准备Agent确保项目目录下或你指定的任何路径有SkyWalking Agent的目录。你可以从Apache SkyWalking官网下载对应版本的二进制包解压后将其中的agent目录拷贝过来。演示项目中可能已自带一个精简版。关键步骤配置启动命令。这是连接应用和SkyWalking后端的关键。不能直接用java -jar启动必须加上Agent参数。java -javaagent:/absolute/path/to/skywalking-agent/skywalking-agent.jar \ -Dskywalking.agent.service_namedemo-application \ -Dskywalking.collector.backend_servicelocalhost:11800 \ -jar target/demo-application-0.0.1-SNAPSHOT.jar参数解析-javaagent: 指定Agent的JAR包路径。必须使用绝对路径相对路径很可能导致加载失败。-Dskywalking.agent.service_name: 为你这个应用在SkyWalking中定义一个服务名称。这是你在UI上看到的核心标识建议按业务功能命名如user-service,order-center。-Dskywalking.collector.backend_service: 指向你刚才启动的SkyWalking OAP Server的gRPC地址默认11800端口。启动成功后应用会正常监听8081端口演示项目配置的server.port。现在这个Spring Boot应用的所有符合条件的方法调用都已经被Agent监控并准备上报数据了。实操心得在IDE如IDEA中启动调试时也需要配置这些VM Options。在“Run/Debug Configurations”的“VM options”栏里填入上述-javaagent等参数才能让调试环境也接入链路追踪这对开发阶段排查问题非常有用。4. 核心功能演示与链路追踪剖析项目启动后我们通过一系列预置的HTTP接口来触发不同类型的链路并在SkyWalking UI中观察结果。4.1 基础HTTP请求链路追踪首先访问一个最简单的接口GET http://localhost:8081/api/hello。这个接口会立刻返回“Hello SkyWalking”。虽然简单但SkyWalking已经捕捉到了这次请求。打开SkyWalking UI (localhost:8080)在顶部导航栏选择“追踪”。在服务下拉框中选择“demo-application”点击查询。你应该能看到一条追踪记录点击进入详情。链路详情解读第一行Span代表整个HTTP请求入口显示为GET:/api/hello。这里包含了总耗时、状态码200、以及它是Entry Span入口跨度。组件显示为SpringMVC说明SkyWalking自动识别并插桩了Spring Web MVC框架。标签Tags包含http.methodGET,url/api/hello,http.status_code200等关键信息。日志Logs如果接口处理中有打印日志需配合日志框架集成这里也会显示。这个简单的例子验证了Agent安装成功并且SkyWalking能够正确接收和展示数据。4.2 模拟跨“服务”内部调用与数据库操作接下来我们触发一个更复杂的链路GET http://localhost:8081/api/order/{id}。这个“订单查询”接口内部模拟了微服务架构中的常见模式OrderController接收请求。OrderService调用UserService的“获取用户信息”方法模拟RPC调用实际是本地方法调用但被Agent识别为内部远程调用。OrderService调用ProductService的“查询商品”方法。ProductService内部会执行一次数据库查询通过Spring Data JPA。在SkyWalking UI中查询这条链路你会看到一棵更丰富的树状图GET:/api/order/{id} (Entry Span) ├── OrderService.getOrder (Local Span) │ ├── UserService.getUser (Local Span) │ └── ProductService.getProduct (Local Span) │ └── /demo-db/product_table/ (Exit Span, Component: Mysql)关键点分析Local SpanOrderService.getOrder这类代表应用内部的一个方法执行段。SkyWalking通过Trace注解或自动插桩生成。演示项目中我们可能在一些关键方法上添加了Trace注解需引入apm-toolkit-trace依赖以增强可观测性。如果没有加Agent也会根据默认规则捕捉一些层级。Exit Span代表应用对外部的调用这里是访问MySQL数据库。SkyWalking的MySQL插件拦截了JDBC操作生成了包含SQL语句可能脱敏、执行时间的Span。这是定位慢SQL的直接依据。层级关系清晰的父子关系展示了调用栈的深度一目了然哪个环节耗时最长。4.3 异步任务与缓存操作的追踪现代应用离不开异步和缓存。演示项目也包含了这两个场景。异步任务访问POST http://localhost:8081/api/async-task会触发一个异步方法执行。在Spring Boot中使用Async注解的方法会在独立线程中运行。SkyWalking通过apm-spring-async插件支持了这种场景。在链路中你会看到主线程的Span结束后产生了一个新的TraceSegment追踪分段来表示异步任务。虽然Segment ID不同但通过Trace ID和Segment ID的关联在UI上仍然可以查看异步任务的执行详情和耗时。Redis缓存操作ProductService在查询数据库前可能会先查询Redis。当项目引入了lettuce或jedis客户端并且SkyWalking Agent包含了对应的插件如apm-lettuce时对Redis的GET、SET等命令也会被记录为一个Exit Span组件显示为Redis。这有助于分析缓存命中率和缓存操作耗时。注意事项异步追踪的完整性依赖于上下文传播Context Propagation。Spring Boot的Async默认使用的SimpleAsyncTaskExecutor不会自动传播上下文。为了确保追踪链路不被中断通常需要配置一个自定义的TaskExecutor或者使用TransmittableThreadLocalTTL这样的库来包装线程池。演示项目中可能已经做了相关配置这是实际项目中容易忽略的一个坑。5. 性能剖析与慢服务检测实战SkyWalking不仅仅展示链路更强大的功能在于性能剖析。我们主动在演示项目中埋下了一些“性能地雷”。5.1 主动触发慢查询与分析方法访问GET http://localhost:8081/api/slow-query。这个接口内部执行了一条包含SLEEP(2)函数的SQL模拟一个耗时2秒的慢查询。在SkyWalking UI中除了在“追踪”页面看到这条慢链路更应该关注“拓扑图”和“性能剖析”功能。拓扑图刷新几次慢查询接口后在拓扑图页面代表demo-application的服务节点颜色可能会变深表示告警或者将鼠标悬停其上可以看到平均响应时间、SLA服务等级协议等指标显著下降。从数据库节点指向应用节点的线条也会变粗表示流量或耗时异常。性能剖析在“性能剖析”页面可以创建一个新的剖析任务。选择服务demo-application设置监控时长然后启动。在剖析期间SkyWalking会定期对正在运行的线程进行采样记录线程堆栈。剖析结束后你会看到一个火焰图Flame Graph或列表直观地展示出在采样期间CPU时间或等待时间主要消耗在哪些方法上。对于这个慢查询你会清晰地看到大部分采样点都落在执行SQL的那个方法栈上。5.2 异常链路追踪与告警配置访问GET http://localhost:8081/api/error。这个接口会主动抛出一个运行时异常。在对应的链路详情中你会看到该Span的状态被标记为错误通常界面显示为红色或有一个错误图标。点击该Span在Tags或Logs中应该能看到异常信息的记录例如error.message和error.stack。这对于快速定位线上故障的根因异常至关重要。更进一步我们可以配置SkyWalking的告警规则。OAP Server内置了一套告警引擎。通过修改config/alarm-settings.yml文件在Docker容器内或OAP发行包中可以定义诸如“服务响应时间超过1秒的百分比大于10%”、“服务错误率大于1%”等规则。例如一个简单的告警规则配置片段rules: service_sla_rule: metrics-name: service_sla op: threshold: 8000 # 小于8000毫秒的SLA4个9是9999 period: 10 count: 2 # 10分钟内连续2次低于阈值 silence-period: 5 # 触发后静默5分钟 message: Service {name} SLA is lower than 80%当触发告警时SkyWalking可以通过webhook将告警信息发送到钉钉、企业微信、Slack等渠道。演示项目虽然没有集成这部分但了解这个流程是构建完整可观测体系的重要一环。6. 高级特性与生产环境考量6.1 日志关联与全链路追踪孤立的链路追踪信息有时还不够我们需要将链路IDTrace ID打入应用日志实现日志与链路的关联。这样在排查问题时可以通过一个Trace ID同时查到链路视图和分散在各个微服务日志文件中的详细日志。SkyWalking提供了与Logback、Log4j2等主流日志框架的集成方案。以Logback为例需要在logback-spring.xml配置中添加%tidTrace ID和%tidSegment ID的转换器并在依赖中引入apm-toolkit-logback-1.x。configuration conversionRule conversionWordtid converterClassorg.apache.skywalking.apm.toolkit.log.logback.v1.x.LogbackPatternConverter/ appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} - %msg%n/pattern /encoder /appender ... /configuration配置后每条日志前都会打印出当前的Trace ID。在SkyWalking UI上查看链路时点击某个Span如果该Span对应的时刻有日志产生UI上可能会直接展示关联的日志片段或者你可以复制Trace ID去日志聚合平台如ELK进行精准搜索。6.2 Agent调优与插件管理生产环境部署Agent时需要考虑性能和资源开销。以下是一些关键配置项通过agent.config文件或JVM系统属性设置agent.sample_n_per_3_secs: 采样率。默认为-1全量采样。在高QPS服务下全量采样会对存储和后端造成压力。可以设置为正整数例如1000表示每秒最多采样1000条链路。对于错误请求SkyWalking通常会强制采样所以不用担心漏掉异常。agent.span_limit_per_segment: 单个Trace Segment可以理解为一个线程内的一次追踪的最大Span数量。默认为300。防止异常情况下产生过多Span导致内存溢出。logging.level: Agent自身的日志级别。生产环境建议设为INFO或ERROR避免过多的DEBUG日志。plugin.*.enabled: 可以控制插件的启用和禁用。例如如果你不用Kafka可以设置plugin.kafka.enabledfalse来减少不必要的类增强提升启动速度。插件管理心得SkyWalking Agent的plugins目录下有很多插件JAR。不是所有插件都需要。你可以根据项目实际使用的技术栈移除不必要的插件如apm-mongodb-plugin如果不用MongoDB。这能减少Agent的加载时间和运行时对类加载器的干扰。6.3 与其他可观测性支柱的联动可观测性的三大支柱是指标Metrics、链路Traces、日志Logs。SkyWalking以链路追踪见长但也提供了指标收集能力如JVM指标、HTTP请求指标。在生产环境中我们通常需要将它们整合。与Prometheus/Grafana集成SkyWalking OAP可以将收集到的指标以Prometheus格式暴露出来配置core.default.metricsExporterprometheus。然后由Prometheus抓取并在Grafana中制作丰富的监控大盘。这样你可以在Grafana里看到服务的QPS、延迟、错误率并在发现异常时通过关联的Trace ID一键跳转到SkyWalking UI查看详细链路。日志聚合如前所述通过Trace ID关联日志。将应用日志集中收集到ELK或Loki中当在SkyWalking中发现问题链路用Trace ID去日志系统搜索可以立刻看到当时服务的详细运行日志和错误堆栈形成排查闭环。7. 常见问题排查与经验实录在实际集成和使用过程中你可能会遇到以下问题。这里记录了我踩过的一些坑和解决方法。7.1 Agent启动与数据上报问题问题1应用启动时报错“Can not find skywalking-agent.jar”。原因-javaagent参数指定的路径不正确。在Shell脚本或IDE配置中使用了相对路径而当前工作目录并非预期目录。解决始终使用绝对路径。可以写一个启动脚本在脚本中动态计算绝对路径例如JAVA_AGENT_PATH$(cd “$(dirname “$0″)/../skywalking-agent”; pwd)/skywalking-agent.jar。问题2应用启动正常但SkyWalking UI中看不到任何服务或链路数据。排查步骤检查后端连通性确认OAP Server是否真的在运行docker ps并确认-Dskywalking.collector.backend_service的IP和端口默认11800是否正确网络是否可达可用telnet命令测试。检查Agent日志在Agent目录下的logs/skywalking-api.log文件中查看是否有错误信息。关注启动时的插件加载日志和运行时的数据上报日志。检查服务名确认UI上选择的服务名称与-Dskywalking.agent.service_name配置完全一致包括大小写。检查采样率确认没有因为采样率设置而丢掉了所有数据。初期调试可设置为-Dskywalking.agent.sample_n_per_3_secs-1全采样。问题3链路数据不完整缺少数据库或Redis调用信息。原因对应的插件未生效。可能原因有①使用的数据库驱动或客户端版本太新或太旧SkyWalking插件不支持②插件被意外禁用。解决查看agent/config/agent.config文件确认对应插件如plugin.mysql,plugin.lettuce的enabled是否为true。查看agent/logs/skywalking-api.log搜索“Instrumentation.*.class”相关日志看插件是否成功对目标类进行了增强。如果确认是版本不支持可以考虑升级SkyWalking Agent版本或者在社区寻找解决方案。7.2 性能与资源开销问题问题接入Agent后应用性能明显下降RT响应时间增加。分析字节码增强和数据的收集、序列化、上报都需要消耗CPU和网络资源。这是引入任何APM都无法避免的额外开销但正常情况下应控制在5%以内。优化建议调整采样率在生产环境对高QPS服务务必启用采样。例如设置agent.sample_n_per_3_secs1000。错误链路会被强制采样所以不影响问题排查。精简插件移除plugins目录下绝对用不到的插件JAR包。调整缓冲区Agent会将数据先缓存在内存队列再批量发送。可以调整agent.buffer_channel_capacity缓冲区大小和agent.remote_downsampling_factor下行采样因子高级特性来平衡内存使用和上报频率。升级版本SkyWalking社区持续在优化性能升级到较新的稳定版可能获得更好的性能表现。7.3 追踪上下文丢失问题问题在异步线程或线程池中追踪链路中断新的线程里看不到父线程的Trace ID。原因这是分布式追踪中的一个经典问题。默认的ThreadLocal无法将上下文自动传递到子线程。解决方案使用TraceCrossThread注解SkyWalking Toolkit提供了apm-toolkit-trace包其中的TraceCrossThread注解可以标注在Callable或Runnable实现类上但这种方式侵入性强。使用TTLTransmittableThreadLocal这是阿里开源的一个库是解决此问题更优雅的方案。你需要引入com.alibaba:transmittable-thread-local依赖。使用TtlExecutors包装原有的ExecutorService。例如Bean public ExecutorService asyncExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); // ... 配置 executor return TtlExecutors.getTtlExecutorService(executor.getThreadPoolExecutor()); }配置Spring的AsyncConfigurer如果你使用Async可以定义一个配置类返回用TTL包装后的执行器。 演示项目如果涉及复杂的异步场景很可能已经采用了类似TTL的方案来保证链路连续性。这是构建可靠可观测性基础设施的关键一步。本文还有配套的精品资源点击获取