SkyWalking全链路追踪工具

一. 什么是 SkyWalking？

1. 定义与背景

• 开源 APM 系统
  Apache SkyWalking 是一款专注于 分布式系统监控、追踪与诊断 的国产开源应用性能管理（APM）工具，由吴晟于 2015 年创建并开源，2017 年进入 Apache 孵化器，2019 年成为 Apache 顶级项目。

• 设计目标
  专为 微服务架构、云原生环境（Kubernetes、Docker）及容器化部署 设计，解决分布式系统中服务链路复杂、性能问题定位困难等痛点。

2. 核心功能

3. 核心优势

• 低侵入性
  通过 Agent 探针实现监控，无需修改业务代码，仅需添加启动参数即可接入。

• 多语言支持
  支持 Java、.NET、Node.js、Go、Python、PHP 等主流语言，覆盖异构技术栈。

• 云原生友好
  深度集成 Kubernetes、Istio、Envoy，支持 Service Mesh 监控。

• 支持主流存储
  Elasticsearch、MySQL、postgresql 、 banyandb等。

• 生态丰富
  提供插件化扩展机制，兼容 OpenTelemetry、Zipkin、Prometheus 等开源生态工具。

二. SkyWalking 架构

SkyWalking 采用 模块化架构，主要组件如下：

• 探针（Agent）：

    部署在应用端，负责采集链路、指标、日志等数据。
    支持多种语言，如 Java Agent、Nginx Lua 模块等。
  

• 后端（OAP Server）：

    接收并处理探针上报的数据，进行聚合、分析。
    提供 GraphQL 和 gRPC 接口供 UI 查询。
  

• 存储（Storage）：

    数据持久化层，默认支持 Elasticsearch、H2、MySQL 等。
  

• 用户界面（UI）：

    可视化展示监控数据，支持拓扑图、链路详情、指标仪表盘等。
  

架构图简示：

三. 服务端搭建步骤

• 环境要求：
  JDK 8+
  存储服务（如 Elasticsearch 7.x）

• 步骤：

1. 下载安装包：
   访问 SkyWalking 官方下载页面 下载最新版本：
   

# 或者用命令下载
wget https://dlcdn.apache.org/skywalking/10.2.0/apache-skywalking-apm-10.2.0.tar.gz  # 选择最新版本
tar -zxvf apache-skywalking-apm-10.2.0.tar.gz
cd apache-skywalking-apm-bin

2. 修改注册中心为nacos

修改 apache-skywalking-apm-bin/config/application.yml

3. 配置存储（以 mysql 为例）：

# 修改 apache-skywalking-apm-bin/config/application.yml：

storage:
  selector: ${SW_STORAGE:mysql}
  mysql:
    properties:
      jdbcUrl: ${SW_JDBC_URL:"jdbc:mysql://localhost:3306/sky_walking?rewriteBatchedStatements=true&allowMultiQueries=true"}
      dataSource.user: ${SW_DATA_SOURCE_USER:root}
      dataSource.password: ${SW_DATA_SOURCE_PASSWORD:12345678}

注意：
2025年3月24日发布的Apache SkyWalking APM 10.2.0版本

No H2, More BanyanDB
	添加BanyanDB 0.8.0支持并作为默认数据库。
	H2存储选项被永久移除。

项目：
为Elasticsearch中需要排序或聚合的字段添加doc_values，并禁用所有其他字段。
此更改不会影响正式发布用户的现有部署及其功能。

警告：如果我们的Elasticsearch索引有自定义查询插件，这个更改可能会破坏它们，
	因为使用意外字段的排序查询和聚合查询会被阻止。

【重大变更】将debug -query模块改名为status-query模块。相对暴露的api不变。

所有skywalking-oap-server的jar不再通过maven central发布我们只会将源tar和二进制tar
发布到网站下载页面，而将docker镜像发布到docker hub。

警告：如果您在项目中使用skywalking-oap-server作为依赖项，
则需要从网站下载源代码tar并将其发布到您的私有maven存储库。

[重大改变]永久移除H2作为存储选项BanyanDB 0.8（需要OAP 10.2）简单、稳定且可用于生产。
不再需要H2作为默认存储。

[重大改变]BanyanDB服务器版本升级到0.8.0此版本与以前的版本不兼容。
请先将BanyanDB服务器升级到0.8.0，再将OAP升级到10.2.0。

为了编译最新的UI(boost - UI)，将nodejs升级到v22.14.0。

将tj-actions/changed-files迁移到dorny/paths-filter。

从10.2.0开始，banyandb配置被分离到一个独立的配置文件：‘ bydb.yaml ’。

4. 手动添加mysql数据驱动包
   因为在oap-libs目录下没有mysql数据驱动，如果不加，配置mysql启动会报错
   

5. 修改UI服务的配置文件
   因为UI服务的端口，默认8080
   打开 /apache-skywalking-apm-bin/webapp/application.yml 配置文件，修改端口

6. 启动服务

   # 启动 OAP 服务：
   # oap服务：对应的启动脚本oapService.bat，Linux/Mac下对应的后缀是sh
   sh bin/oapService.sh start
   
   # 启动 UI：
   # 对应的启动脚本webappService.bat，Linux/Mac下对应的后缀是sh
   sh bin/webappService.sh start
   
   # 还有一个 bin/startup.bat 启动文件，可以直接启动上述两个服务
   
   

   skywalking-oap-server 服务启动后会暴露 11800 和 12800 两个端口，
   分别为收集监控数据的端口 11800 和接收前端请求的端口 12800 ，
   端口可以修改/config/application.yml

7. 访问 UI
   浏览器打开 http://localhost:8088。

   

8. 客户端搭建（以 Java 为例）
   下载 Agent：
   从 SkyWalking 发布页获取 skywalking-agent.jar。

   

9. 启动应用时挂载 Agent：
   在运行的程序配置VM options参数

   java -javaagent:/path/to/skywalking-agent.jar 
   	-Dskywalking.agent.service_name=your-service-name 
   	-jar your-app.jar
   

   

注意事项：由于Skywalking 默认是不支持 Spring Cloud Gateway ，若为Cloud服务，需要将optional-plugins目录中最新的apm-spring-cloud-gateway*.jar 放入 plugins目录中

目前Skywalking还不支持 spring cloud gateway 4.x（截止2025年5月）
查阅了大量文档，在github的issue得到答案
原话为：I think this has been answered repeatedly. Spring Gateway 4 is not supported, as no one contributed.

https://github.com/apache/skywalking/discussions/12675
https://github.com/apache/skywalking/discussions/12636

10. 目录结构

    webapp： UI 前端（web 监控页面）的 jar 包和配置文件
    oap-libs： 后台应用的 jar 包，以及它的依赖 jar 包，里边有一个 server-starter-*.jar 就是启动程序
    config： 启动后台应用程序的配置文件，是使用的各种配置文件
    bin： 各种启动脚本，一般使用脚本 startup.sh 来启动 web页面 和对应的 后台应用

    • oapService.*： 默认使用的后台程序和启动脚本：（使用的是默认模式启动，还支持其它模 式，各种模式区别见 启动模式）
    • oapServiceInit.*： 使用 init 模式启动；再次模式下，OAP 服务器启动以执行初始化工作，然后退出
    • oapServiceNoInit.*： 使用 No Init 模式启动；在此模式下， OAP 服务不进行初始化
    • startup.*： 组合脚本，同时启动 oapService. *；webappService. * 脚本

    agent： (在搭建微服务的时候会用到)

    • skywalking-agent.jar： 代理服务 jar 包
    • config： 代理服务启动时使用的配置文件
    • plugins： 包含多个插件，代理服务启动时会加载该目录下的所有插件（实际是各种 jar 包）
    • optional-plugins： 可选插件，当然需要支持某种功能时，比如 SpringCloud Gateway，则需要把对应的 jar 包拷贝到 plugins 目录下

四. 日志监控

SkyWalking 原生日志收集：

日志框架集成：

• log4j

• log4j2

• logback

Log4j/Logback：配置 SkyWalkingLogAppender。

<dependency>
   <groupId>org.apache.skywalking</groupId>
   <artifactId>apm-toolkit-logback-1.x</artifactId>
   <version>${project.release.version}</version>
</dependency>

示例 Logback 配置：

<?xml version="1.0" encoding="UTF-8" ?>
<configuration>

    <!--  引入 SpringBoot 默认的 logback XML 配置文件  -->
    <include resource="org/springframework/boot/logging/logback/defaults.xml" />

    <appender name="console" 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>-%clr(%d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd HH:mm:ss.SSS}}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} [%tid] %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}}</Pattern>
            </layout>
        </encoder>

    </appender>

    <!--  设置 Appender  -->
    <root level="INFO">
        <appender-ref ref="console"></appender-ref>
    </root>


</configuration>

Skywalking 通过 grpc 上报日志（需要v8.4.0+）

<?xml version="1.0" encoding="UTF-8" ?>
<configuration>

    <!--  引入 SpringBoot 默认的 logback XML 配置文件  -->
    <include resource="org/springframework/boot/logging/logback/defaults.xml" />

    <appender name="console" 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>-%clr(%d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd HH:mm:ss.SSS}}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} [%tid] %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}}</Pattern>
            </layout>
        </encoder>

    </appender>

    <appender name="grpc-log" class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.log.GRPCLogClientAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.mdc.TraceIdMDCPatternLogbackLayout">
                <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{tid}] [%thread] %-5level %logger{36} -%msg%n</Pattern>
            </layout>
        </encoder>
    </appender>

    <!--  设置 Appender  -->
    <root level="INFO">
        <appender-ref ref="console" />
        <appender-ref ref="grpc-log" />
    </root>


</configuration>

注意：如果 SkyWalking 服务不是部署在本地，日志无法上报到 SkyWalking 需要修改\agent\config目录下的agent.config文件

将下面信息复制到文件底部

plugin.toolkit.log.grpc.reporter.server_host=${SW_GRPC_LOG_SERVER_HOST:127.0.0.1}
plugin.toolkit.log.grpc.reporter.server_port=${SW_GRPC_LOG_SERVER_PORT:11800}
plugin.toolkit.log.grpc.reporter.max_message_size=${SW_GRPC_LOG_MAX_MESSAGE_SIZE:10485760}
plugin.toolkit.log.grpc.reporter.upstream_timeout=${SW_GRPC_LOG_GRPC_UPSTREAM_TIMEOUT:30}

五. 监控告警配置

• 版本支持：自 SkyWalking 6.x 版本引入告警功能，通过动态规则引擎实时监控指标并触发通知。
• 核心机制：
  • 告警规则：定义监控指标的条件和触发阈值。
  • Webhook （网络钩子）回调：配置告警触发后的通知目标（如 HTTP 接口、钉钉机器人、邮件等）。
  • 配置文件：config/alarm-settings.yml（支持热更新，修改后无需重启 OAP）。

SkyWalking 告警功能的流程图

SkyWalking 从 v9.x 开始逐步引入 MQE（Monitoring Query Expression） 语法，替代旧版的 metrics-name + threshold 模式，v10+ 版本默认强制使用 MQE。核心变化如下：

1. 告警规则文件：
   修改 apache-skywalking-apm-bin/config/alarm-settings.yml，
   apache-skywalking-apm-10.x版本示例规则：

rules:
  # 规则名称需以 _rule 结尾
  service_resp_time_rule:
   # MQE 表达式，计算结果需为布尔值（1=true触发告警，0=false不触发）
    expression: sum(service_resp_time > 1000) >= 3
    period: 10        # 评估周期（单位：分钟）
    silence-period: 5 # 静默期（单位：分钟）
    message: "Response time of service {name} is more than 1000ms in 3 minutes of last 10 minutes." # 自定义消息内容，支持变量（如 {name}）
  # 更多规则...

2. 常用监控指标

3. 示例：定义接口响应时间告警

rules:
  service_resp_time_rule:
  expression: avg(service_resp_time) > 1000  # 平均响应时间 >1s
  threshold: 3000  # 3000 毫秒（3 秒）
  period: 5  # 统计最近 5 分钟的指标
  count: 2  # 5 分钟内超过阈值至少 2 次
  silence-period: 10  # 触发后 10 分钟内不重复告警
  message: 服务 {name} 的平均响应时间超过 3 秒，当前值为 {value} 毫秒。

4. Webhook 定义

hooks:                     # Webhook 总配置
  webhook:                 # Webhook 类型（支持 future 扩展其他 hook 类型）
    default:               # 配置组名称（可自定义，如 dingtalk、wechat）
      is-default: true     # 是否作为默认组（true 时所有告警规则默认触发此组）
      urls:                # 接收告警的 HTTP 端点列表
        - http://127.0.0.1:8080/alert
        - http://api.example.com/notify
      # headers:           # 自定义请求头（如 Content-Type、认证信息）
      #   Content-Type: application/json
      #   Authorization: Bearer xxxx
      # secret: "your-signing-secret"  # （可选）请求签名密钥
      # body: |            # 自定义请求体模板（支持变量替换）
      #   {
      #     "alert": "{alarmMessage}",
      #     "scope": "{scope}"
      #   }

5. 集成第三方通知工具

hooks:
  webhook:
    internal_system:        # 内部运维平台
      urls:
        - http://internal-monitor.example.com/alerts
      headers:
        X-Auth-Token: "xxx"
    
    dingtalk:               # 钉钉机器人
      urls:
        - https://oapi.dingtalk.com/robot/send?access_token=your_token
      secret: "钉钉签名密钥"  # 若机器人启用加签，需填写
      body: |
        {
          "msgtype": "markdown",
          "markdown": {
            "title": "SkyWalking 告警通知",
            "text": "**告警名称**: {alarmMessage}\n**服务名称**: {name}"
          }
        }
       
    wechat:                 # 企业微信机器人
      urls:
        - https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your_key
      body: |
        {
          "msgtype": "text",
          "text": {
            "content": "SkyWalking 告警通知\n规则: {ruleName}\n消息: {alarmMessage}\n时间: {startTime}"
          }
        }

6. 告警变量清单
   在 body 或 message 中可使用的动态变量：

7. 邮件通知
   需通过中间服务（如 Python 脚本）接收 Webhook 并发送邮件，或使用 SkyWalking 的邮件插件（需扩展开发）。

总结

SkyWalking 是一个功能全面的 APM 工具，通过 Agent 无侵入采集数据，OAP 服务处理，结合 Elasticsearch 存储实现高性能监控。日志和告警功能可通过配置灵活扩展，适合云原生及微服务架构。

官网：https://skywalking.apache.org/
下载：https://skywalking.apache.org/downloads/
Github：https://github.com/apache/skywalking
Agent文档：https://skywalking.apache.org/docs/main/
OAP文档：https://skywalking.apache.org/docs/skywalking-showcase/next/readme/
中文文档：https://skyapm.github.io/document-cn-translation-of-skywalking/