下面是一份 完整的 Spring Boot 应用接入 SkyWalking Agent 的实战示例，涵盖从环境准备、项目创建、Agent 配置到验证的全过程，适合新手快速上手。

---

🚀 Spring Boot 接入 SkyWalking Agent 完整示例

✅ 目标：
创建一个简单的 Spring Boot Web 应用，接入 SkyWalking Java Agent，实现无侵入式链路追踪、JVM 监控、服务拓扑等功能。

---

一、前置准备

1. 已运行 SkyWalking OAP + UI

请确保你已按之前教程启动了 SkyWalking 环境，例如使用 Docker Compose：

git clone https://github.com/apache/skywalking-docker.git
cd skywalking-docker/compose/9.7.0/elasticsearch
docker-compose up -d

访问 UI 验证：http://localhost:8080

---

二、创建 Spring Boot 项目

方法 1：使用 Spring Initializr

• Project: Maven
• Language: Java
• Spring Boot: 2.7.0（或 3.x）
• Group: com.example
• Artifact: demo-skywalking
• Dependencies:
  • Spring Web
  • Spring Boot Actuator（可选，用于健康检查）

方法 2：手动创建 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>demo-skywalking</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.0</version>
        <relativePath/>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

---

三、编写简单 Controller

创建文件：src/main/java/com/example/DemoController.java

package com.example;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello from SkyWalking!";
    }

    @GetMapping("/chain")
    public String chain() throws InterruptedException {
        // 模拟调用下游（可扩展为真实服务）
        Thread.sleep(100); // 模拟处理耗时
        return "Chain call completed";
    }
}

---

四、下载并配置 SkyWalking Agent

1. 下载 SkyWalking 发行版

wget https://downloads.apache.org/skywalking/9.7.0/apache-skywalking-apm-9.7.0.tar.gz
tar -xzf apache-skywalking-apm-9.7.0.tar.gz

解压后你会得到：

apache-skywalking-apm-bin/
└── agent/
    ├── skywalking-agent.jar
    └── ...

记下路径，如：/your/path/to/apache-skywalking-apm-bin/agent

---

五、启动 Spring Boot 应用并挂载 Agent

方式 1：命令行启动（开发测试）

java \
  -javaagent:/your/path/to/apache-skywalking-apm-bin/agent/skywalking-agent.jar \
  -DSW_AGENT_NAME=demo-springboot-service \
  -DSW_AGENT_COLLECTOR_BACKEND_SERVICES=localhost:11800 \
  -DSW_AGENT_SAMPLE_RATE=10000 \
  -jar target/demo-skywalking-1.0.0.jar

参数说明：

参数	值	说明
-javaagent	指向 skywalking-agent.jar	必需
-DSW_AGENT_NAME	demo-springboot-service	在 UI 中显示的服务名
-DSW_AGENT_COLLECTOR_BACKEND_SERVICES	localhost:11800	OAP gRPC 地址
-DSW_AGENT_SAMPLE_RATE	10000	100% 采样（调试用）

---

方式 2：Docker 启动（生产推荐）

创建 Dockerfile：

FROM openjdk:8-jre-slim

# 复制 SkyWalking Agent
COPY --from=apache/skywalking-java-agent:9.7.0 /skywalking/agent /skywalking/agent

# 复制应用
COPY target/demo-skywalking-1.0.0.jar /app.jar

# 启动命令
ENTRYPOINT ["java", \
  "-javaagent:/skywalking/agent/skywalking-agent.jar", \
  "-DSW_AGENT_NAME=demo-springboot-service", \
  "-DSW_AGENT_COLLECTOR_BACKEND_SERVICES=skywalking-oap:11800", \
  "-jar", "/app.jar"]

构建并运行：

docker build -t demo-skywalking .
docker run -d --network=host --name demo-app demo-skywalking

🔁 注意：如果 OAP 在另一个容器中，确保网络互通（如 --network=skywalking）

---

六、验证接入是否成功

1. 发起请求触发调用

curl http://localhost:8080/hello
curl http://localhost:8080/chain

2. 打开 SkyWalking UI

访问：http://localhost:8080

3. 查看结果

功能	验证方法
✅ 服务出现	Dashboard → 服务列表中看到 demo-springboot-service
✅ 调用链	Trace 页面 → 查询 /hello 或 /chain 的调用链
✅ 拓扑图	Topology → 出现新节点，可能带 Tomcat 边
✅ JVM 指标	服务详情 → 查看 CPU、内存、GC 等
✅ 端点监控	Endpoint 页面 → 看到 /hello, /chain 的 P99 耗时

🎉 成功标志：看到完整的调用链，Span 包含 Controller、Tomcat 等信息。

---

七、进阶配置（可选）

1. 日志中输出 Trace ID（便于关联）

修改 application.yml：

logging:
  pattern:
    console: "%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - traceId=%X{trace_id} %msg%n"

日志输出示例：

10:30:12.345 [http-nio-8080-exec-1] INFO  DemoController - traceId=abc123-def456 Hello from SkyWalking!

2. 排除不需要监控的插件（降低开销）

在启动命令中添加：

-DSW_AGENT_PLUGIN_EXCLUDE_PLUGINS=mysql,redis

---

八、常见问题排查

问题	解决方案
服务未出现在 UI	检查 -javaagent 路径、OAP 地址、防火墙
无调用链数据	确保发起 HTTP 请求，检查采样率
Agent 启动报错	查看 logs/skywalking-api.log
中文乱码	设置 -Dfile.encoding=UTF-8
Docker 中连接不到 OAP	使用容器名或 host.docker.internal

---

✅ 总结：接入四步法

步骤	命令 / 操作
1️⃣ 下载 Agent	wget + tar 解压
2️⃣ 编写 Spring Boot 应用	Controller + Maven
3️⃣ 启动时挂载 Agent	-javaagent + JVM 参数
4️⃣ 验证数据上报	UI 查看服务、链路、拓扑

---

📦 项目结构完整示例

demo-skywalking/
├── pom.xml
├── src/
│   └── main/
│       ├── java/com/example/DemoController.java
│       └── resources/application.yml
├── Dockerfile
└── target/demo-skywalking-1.0.0.jar

---

🎁 附件：点击下载完整示例代码 ZIP（可参考官方示例）