SkyWalking 集成 Spring Cloud Alibaba 全链路追踪实战

在终端中执行 docker-compose up -d，等待几分钟，所有服务就会启动完毕。

• Nacos: 访问 http://localhost:8848/nacos，默认账号密码都是 nacos。
• SkyWalking UI: 访问 http://localhost:8080，即可看到 SkyWalking 的仪表盘。

现在，我们的基础设施已经就绪！接下来，让我们开始构建微服务应用。

2. 构建 Spring Cloud Alibaba 微服务项目

我们将构建一个简单的电商场景：用户下单。这个场景涉及两个核心服务：

• order-service: 订单服务，负责创建订单。
• inventory-service: 库存服务，负责扣减库存。

order-service 会通过 Feign 调用 inventory-service。

2.1 创建父工程

首先，创建一个 Maven 父工程 skywalking-sca-demo，用于统一管理依赖版本。

<?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>skywalking-sca-demo</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>
    <modules>
        <module>order-service</module>
        <module>inventory-service</module>
    </modules>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.18</version>
        <relativePath/>
    </parent>
    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <spring-cloud.version>2021.0.8</spring-cloud.version>
        <spring-cloud-alibaba.version>2021.0.5.0</spring-cloud-alibaba.version>
    </properties>
    <dependencyManagement>
        <dependencies>
            <!-- Spring Cloud -->
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- Spring Cloud Alibaba -->
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                <version>${spring-cloud-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

2.2 构建 inventory-service（库存服务）

这是一个简单的服务，提供一个 /deduct 接口用于扣减库存。

1. 添加依赖 (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>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>skywalking-sca-demo</artifactId>
        <version>1.0.0</version>
    </parent>
    <artifactId>inventory-service</artifactId>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Nacos 服务发现 -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>
    </dependencies>
</project>

2. 配置文件 (application.yml):

server:
  port: 8082
spring:
  application:
    name: inventory-service # 服务名，在 Nacos 中注册
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848 # Nacos 地址
management:
  endpoints:
    web:
      exposure:
        include: '*' # 开启 Actuator 健康检查端点，便于 SkyWalking 监控

3. 主启动类:

package com.example.inventory;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient // 启用服务发现
public class InventoryServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(InventoryServiceApplication.class, args);
    }
}

4. 控制器:

package com.example.inventory.controller;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/inventory")
public class InventoryController {
    private static final Logger log = LoggerFactory.getLogger(InventoryController.class);

    @PostMapping("/deduct")
    public String deduct(@RequestParam String productId, @RequestParam Integer count) {
        log.info("收到扣减库存请求：productId={}, count={}", productId, count);
        // 模拟业务处理时间
        try {
            Thread.sleep(200);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        log.info("库存扣减成功");
        return "success";
    }
}

2.3 构建 order-service（订单服务）

这个服务会暴露一个 /create 接口，并通过 Feign 调用 inventory-service。

1. 添加依赖 (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>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>skywalking-sca-demo</artifactId>
        <version>1.0.0</version>
    </parent>
    <artifactId>order-service</artifactId>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Nacos 服务发现 -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>
        <!-- OpenFeign 用于服务间调用 -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-openfeign</artifactId>
        </dependency>
    </dependencies>
</project>

2. 配置文件 (application.yml):

server:
  port: 8081
spring:
  application:
    name: order-service
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
    feign:
      client:
        config:
          default:
            connectTimeout: 5000
            readTimeout: 5000
management:
  endpoints:
    web:
      exposure:
        include: '*'

3. 主启动类:

package com.example.order;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.openfeign.EnableFeignClients;

@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients // 启用 Feign
public class OrderServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}

4. 定义 Feign Client:

package com.example.order.feign;

import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

// value 指向 Nacos 中注册的服务名
@FeignClient(value = "inventory-service")
public interface InventoryFeignClient {
    @PostMapping("/inventory/deduct")
    String deduct(@RequestParam("productId") String productId, @RequestParam("count") Integer count);
}

5. 控制器:

package com.example.order.controller;

import com.example.order.feign.InventoryFeignClient;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/order")
public class OrderController {
    private static final Logger log = LoggerFactory.getLogger(OrderController.class);

    @Autowired
    private InventoryFeignClient inventoryFeignClient;

    @PostMapping("/create")
    public String createOrder(@RequestParam String userId, @RequestParam String productId, @RequestParam Integer count) {
        log.info("收到创建订单请求：userId={}, productId={}, count={}", userId, productId, count);
        // 调用库存服务
        String result = inventoryFeignClient.deduct(productId, count);
        log.info("订单创建成功");
        return "order created, inventory result: " + result;
    }
}

2.4 验证基础功能

现在，我们可以分别启动两个服务。

1. 启动 inventory-service。
2. 启动 order-service。

访问 Nacos 控制台 (http://localhost:8848/nacos)，你应该能看到 order-service 和 inventory-service 都已成功注册。

然后，使用 curl 或 Postman 调用订单服务：

curl -X POST "http://localhost:8081/order/create?userId=1&productId=P001&count=1"

如果返回 order created, inventory result: success，说明我们的微服务调用链路是通的！

然而，此时如果我们想了解这次调用的详细耗时、经过了哪些服务，或者排查性能瓶颈，我们无从下手。这就是 SkyWalking 大显身手的时候了。

3. 集成 SkyWalking Agent

SkyWalking 的核心在于其 Java Agent。它通过字节码增强技术，在应用运行时动态地注入追踪逻辑，无需修改一行业务代码。

3.1 下载 SkyWalking Agent

访问 Apache SkyWalking 官方下载页面，下载与你的 OAP Server 版本（9.7.0）匹配的 Agent 包。通常选择 apache-skywalking-java-agent-*.tar.gz。

下载后，将其解压到一个目录，例如 /opt/skywalking-agent。解压后的目录结构大致如下：

skywalking-agent/
 ├── activations/
 ├── bootstrap-plugins/
 ├── config/
 │   └── agent.config <-- 主配置文件
 ├── licenses/
 ├── logs/
 ├── optional-plugins/
 ├── plugins/
 └── skywalking-agent.jar <-- 核心 Jar 包

3.2 配置 Agent

我们需要对 config/agent.config 文件进行一些关键配置。

# The service name in UI
agent.service_name=${SW_AGENT_NAME:Your_ApplicationName}
# Backend service addresses.
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800}
# Logging file name
logging.file_name=${SW_LOGGING_FILE_NAME:skywalking-api.log}
# Logging level
logging.level=${SW_LOGGING_LEVEL:INFO}

我们将为两个服务创建各自的配置文件，以区分它们在 SkyWalking UI 中的显示。

为 inventory-service 创建配置:
在 skywalking-agent/config/ 目录下创建 inventory-service.config:

agent.service_name=inventory-service
collector.backend_service=127.0.0.1:11800

为 order-service 创建配置:
在 skywalking-agent/config/ 目录下创建 order-service.config:

agent.service_name=order-service
collector.backend_service=127.0.0.1:11800

3.3 启动应用并挂载 Agent

现在，我们需要通过 -javaagent 参数来启动我们的 Java 应用。

启动 inventory-service

java -javaagent:/opt/skywalking-agent/skywalking-agent.jar \
-Dskywalking.agent.config_path=/opt/skywalking-agent/config/inventory-service.config \
-jar inventory-service/target/inventory-service-1.0.0.jar

启动 order-service

java -javaagent:/opt/skywalking-agent/skywalking-agent.jar \
-Dskywalking.agent.config_path=/opt/skywalking-agent/config/order-service.config \
-jar order-service/target/order-service-1.0.0.jar

注意: 请将 /opt/skywalking-agent 替换为你实际的 Agent 路径。

启动成功后，你会在应用的日志中看到类似 [SkyWalking Agent] ... 的信息，表明 Agent 已成功加载。

3.4 验证追踪效果

再次调用我们的订单接口：

curl -X POST "http://localhost:8081/order/create?userId=1&productId=P001&count=1"

然后，打开 SkyWalking UI (http://localhost:8080)。

1. 查看服务拓扑图:
   在左侧菜单栏点击 Topology。你会看到一个清晰的拓扑图，展示了 order-service 和 inventory-service 之间的调用关系。箭头方向表示调用流向。
2. 查看追踪列表:
   点击 Trace 菜单。在这里，你可以看到所有被追踪的请求。找到你刚刚发起的请求（可以通过时间、Endpoint /order/create 来筛选），点击它。
3. 分析追踪详情:
   在追踪详情页，你会看到一个非常直观的瀑布流图（Gantt Chart）。它清晰地展示了整个调用链路：通过这个图，你可以一目了然地看出哪个环节最耗时。例如，如果 inventory-service 的处理时间很长，那么问题很可能出在库存服务本身。
   • 最顶层是 order-service 的 /order/create 请求。
   • 展开后，可以看到它内部调用了 inventory-service 的 /inventory/deduct。
   • 每个 Span 都标注了耗时，以及发生的时间线。

4. 深入 SkyWalking：自定义追踪与告警

虽然 SkyWalking Agent 已经为我们自动追踪了大部分场景（如 Spring MVC, Feign, JDBC, Redis 等），但在某些复杂的业务逻辑中，我们可能希望手动创建 Span 来追踪特定的代码块，或者设置告警规则。

4.1 手动埋点（Manual Context Propagation）

假设在 order-service 中，除了调用库存服务，我们还需要记录一个重要的业务日志到数据库，并且我们希望这个数据库操作也能体现在追踪链路中。

1. 添加数据库依赖:
   在 order-service/pom.xml 中添加 H2 数据库和 MyBatis 依赖（仅用于演示）。

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>2.3.0</version>
</dependency>

2. 配置数据库 (application.yml):

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
    username: sa
    password: password

3. 在 Service 中手动埋点:
   SkyWalking 提供了 TraceContext API 来手动创建 Span。

创建 Mapper 和实体:

// Order.java
public class Order {
    private Long id;
    private String userId;
    private String productId;
    private Integer count;
    // getters and setters...
}

// OrderMapper.java
@Mapper
public interface OrderMapper {
    @Insert("INSERT INTO orders(user_id, product_id, count) VALUES(#{userId}, #{productId}, #{count})")
    void insert(Order order);
}

package com.example.order.service;

import com.example.order.feign.InventoryFeignAssistant;
import com.example.order.mapper.OrderMapper;
import com.example.order.model.Order;
import org.apache.skywalking.apm.toolkit.trace.Trace;
import org.apache.skywalking.apm.toolkit.trace.TraceContext;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class OrderService {
    private static final Logger log = LoggerFactory.getLogger(OrderService.class);

    @Autowired
    private InventoryFeignAssistant inventoryFeignAssistant;

    @Autowired
    private OrderMapper orderMapper;

    // 使用 @Trace 注解可以自动为方法创建 Span
    @Trace
    public String createOrder(String userId, String productId, Integer count) {
        log.info("开始创建订单");
        // 手动创建一个 Span 来包裹数据库操作
        String before = TraceContext.traceId();
        try (final var ignored = TraceContext.createLocalSpan("OrderService.saveToDB")) {
            Order order = new Order();
            order.setUserId(userId);
            order.setProductId(productId);
            order.setCount(count);
            orderMapper.insert(order);
            log.info("订单已保存到数据库");
        }
        // 调用库存服务（Feign 调用会被自动追踪）
        String result = inventoryFeignAssistant.deduct(productId, count);
        log.info("订单创建流程结束");
        return "success";
    }
}

同时，别忘了在 Controller 中调用这个 Service。

// OrderController.java
@Autowired
private OrderService orderService;
@PostMapping("/create")
public String createOrder(...) {
    return orderService.createOrder(userId, productId, count);
}

现在，当你再次发起请求并在 SkyWalking UI 中查看追踪详情时，你会发现多了一个名为 OrderService.saveToDB 的 Span，它精确地反映了数据库插入操作的耗时。

4.2 配置告警

SkyWalking 不仅能追踪，还能根据预设的规则进行告警。这对于及时发现线上问题至关重要。

SkyWalking 的告警规则配置在 OAP Server 的 config/alarm-settings.yml 文件中。由于我们是用 Docker 启动的，需要进入容器进行修改。

1. 添加一个简单的告警规则:
   例如，我们希望当 order-service 的 /order/create 接口的平均响应时间超过 500ms 时，触发告警。

编辑告警配置文件:

rules:
  # Rule unique name, must be unique
  service_resp_time_rule:
    # Metrics names to be monitored. Only one metric per rule is allowed
    metrics-name: service_resp_time
    # The threshold of the metrics. The value should be a number
    threshold: 500
    # The period of time in minutes to evaluate the metrics
    period: 10
    # How many times after the metrics exceed the threshold, will trigger alarm
    count: 1
    # The silence period in minutes after alarm triggered
    silence-period: 10
    # Define the scope of the rule
    include-names:
      - order-service
    exclude-names:
      - .*unstable.*
    # Regular expression, if you want to exclude some services.
    # The message format for the alarm
    message: Response time of service {name} is more than {value} ms in {period} minutes.
    webhooks:
      # Add your webhook URL here to receive alarm messages.
      # - http://your-webhook-url

重启 OAP 容器:
修改完配置后，需要重启容器使配置生效。

docker restart skywalking-oap

现在，如果你故意在 order-service 中增加一个长时间的 Thread.sleep(600)，然后持续调用接口，SkyWalking 就会触发告警。告警信息会显示在 UI 的 Alarm 菜单中。

提示: 在生产环境中，通常会将告警消息通过 Webhook 发送到钉钉、企业微信或 Slack 等即时通讯工具，以便团队能第一时间收到通知。

5. 高级特性与最佳实践

掌握了基础用法后，让我们探讨一些更高级的特性和在生产环境中应该遵循的最佳实践。

5.1 日志集成（Log Integration）

追踪（Trace）和日志（Log）是可观测性的两大支柱。将它们关联起来，可以极大地提升问题排查效率。SkyWalking 支持将 TraceId 和 SpanId 注入到应用日志中。

1. 配置 logback-spring.xml:
   在 resources 目录下创建 logback-spring.xml 文件。

在 pom.xml 中添加依赖:

<!-- SkyWalking Logback 插件 -->
<dependency>
    <groupId>org.apache.skywalking</groupId>
    <artifactId>apm-toolkit-logback-1.x</artifactId>
    <version>8.16.0</version>
    <!-- 与 Agent 版本保持一致 -->
</dependency>

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
                <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} -%msg%n</pattern>
            </layout>
        </encoder>
    </appender>
    <root level="INFO">
        <appender-ref ref="STDOUT"/>
    </root>
</configuration>

关键点在于 %tid，它会被 SkyWalking Agent 自动替换为当前的 TraceId。

现在，当你查看应用日志时，每条日志都会带上一个唯一的 TraceId。例如：

2023-10-27 10:00:00.123 [TID:1234567890abcdef] [http-nio-8081-exec-1] INFO c.e.o.c.OrderController - 收到创建订单请求...

在 SkyWalking UI 的追踪详情页，你也可以直接点击 Logs 标签，看到与该 Trace 关联的所有日志，前提是你的日志系统（如 ELK）也集成了 SkyWalking 的日志格式。

5.2 性能剖析（Profile）

当某个接口突然变慢，但常规的追踪无法定位到具体是哪一行代码导致的，这时就可以使用 SkyWalking 的 Performance Profiling 功能。它可以在不重启应用的情况下，对指定的 Endpoint 进行 CPU 热点分析。

1. 在 SkyWalking UI 中，进入 Trace 页面，找到那个慢的请求。
2. 在该 Trace 的详情页，点击右上角的 Profile 按钮。
3. 设置采样间隔（如 10ms）和最大采样数（如 1000）。
4. 确认后，SkyWalking 会自动在目标 JVM 上开启一个剖析任务。
5. 任务完成后，你可以在 Profile 菜单中看到详细的火焰图（Flame Graph），它能精确地告诉你 CPU 时间都花在了哪些方法上。

这是一个非常强大的在线诊断工具，对于解决偶发性性能问题极为有效。

5.3 生产环境最佳实践

1. 存储选型: 本文为了方便，使用了 H2 内存数据库。但在生产环境中，必须使用 Elasticsearch 作为 SkyWalking 的后端存储，以保证数据的持久化和高可用性。
2. Agent 升级: 尽量保持 Agent 和 OAP Server 的版本一致，以避免兼容性问题。
3. 采样率: 对于高流量的应用，可以适当调整采样率（agent.sample_n_per_3_secs），避免上报过多数据给 OAP Server 带来压力。
4. 安全: OAP Server 的 gRPC 和 HTTP 端口应做好网络安全隔离，避免暴露在公网。
5. 资源监控: 监控 OAP Server 本身的 CPU、内存和磁盘 I/O，确保其健康运行。

6. 总结与展望

通过本文的实战，我们成功地将 Apache SkyWalking 集成到了一个基于 Spring Cloud Alibaba 的微服务项目中。我们不仅实现了自动化的全链路追踪，还学习了如何手动埋点、配置告警、集成日志以及使用性能剖析等高级功能。

SkyWalking 以其无侵入性、强大的可视化能力和丰富的生态系统，成为了微服务可观测性领域的佼佼者。它帮助我们从'盲人摸象'式的故障排查，转变为'上帝视角'下的精准定位，极大地提升了研发和运维效率。

未来，随着云原生和 Service Mesh 的进一步发展，SkyWalking 也在积极拥抱 eBPF、OpenTelemetry 等新技术，为更复杂的混合架构提供统一的可观测性解决方案。对于每一位致力于构建稳定、高效、可维护的现代应用的开发者来说，掌握 SkyWalking 这样的 APM 工具，已经成为一项必备技能。

希望这篇详尽的实战指南能为你在微服务之路上点亮一盏明灯！