HelloWorld SkyWalking 使用指南

要快速上手 HelloWorld SkyWalking，建议用官方示例配合 Docker Compose 同时启动 OAP 与 UI，再把 Java agent 或浏览器探针部署到示例服务，产生调用链与指标；通过 UI 查看拓扑、跟踪与告警，并按需调整采样与存储配置，就能在本地完整体验 SkyWalking 的链路追踪与性能诊断流程。

先弄清楚：SkyWalking 是什么，HelloWorld 想给你看什么

SkyWalking 是一套分布式系统的可观测性平台，做的是链路追踪、指标监控和服务拓扑绘制。HelloWorld 示例就是把这套功能缩小到一个可跑的场景：启动 OAP（后端）、UI（前端）和若干个示例服务，并用 agent 或探针把数据上报到 OAP，让你能看到调用链、服务拓扑、请求耗时等。

必备环境与概念（先把地基打稳）

• 基础软件：Docker 与 docker-compose（最省力），或本地 JDK（如果你想跑原生 Java agent）。
• 核心组件：Agent（埋点），OAP（处理与存储中转），UI（可视化），可选外部存储如 Elasticsearch、MySQL、H2（仅测试）。
• 数据流向：Agent → OAP（接收）→ 存储（持久化）→ UI（读取并展示）。
• 采样与性能：采样率、批量上报策略决定性能与可观测精度平衡。

快速上手：一步步实操（最容易复现的路线）

步骤一：用 Docker Compose 启动 SkyWalking

下面是一份最小化的 docker-compose 示例，适合本地试验（仅演示结构，真实使用请参考官方配置并根据磁盘/内存调整）。

version: '3'
services:
  oap:
    image: apache/skywalking-oap-server:9.0.0
    ports:
      - "11800:11800"   # gRPC 接收 agent 数据
      - "12800:12800"   # REST/HTTP 接口
  ui:
    image: apache/skywalking-ui:9.0.0
    ports:
      - "8080:8080"
    depends_on:
      - oap

启动命令：

docker-compose up -d

启动后访问 http://localhost:8080（UI），如果能打开页面表示后端与前端基本连通。

步骤二：运行示例服务并接入 Agent

常见的 HelloWorld 示例是一个简单的 Java 服务（Spring Boot），通过 SkyWalking Java agent 上报。操作要点：

• 下载对应版本的 skywalking-agent，放在服务的同级目录。
• 启动服务时加上 JVM 参数：-javaagent:/path/to/skywalking-agent.jar 并设置 Agent 后端地址，例如在 agent/config/agent.config 或通过系统属性指定。

示例启动命令：

java -jar -javaagent:skywalking-agent.jar -Dskywalking.collector.backend_service=127.0.0.1:11800 app.jar

Agent 会自动拦截常用框架（Spring、gRPC、JDBC 等），把链路、日志上下文和指标上报给 OAP。

步骤三：生成流量并在 UI 中观察

• 用 curl、Postman 或浏览器访问示例接口，确保产生请求。
• 在 UI 中可以看到：服务拓扑（Services）、单次调用链（Traces）、服务实例的指标（Metrics）、以及告警（如果配置）。
• 观察点：请求分布、慢调用（long tail）、异常堆栈。

关键配置详解（别迷糊这些选项）

• agent.config：主要关心 collector.backend_service（OAP 地址）、采样率（sampling）、日志上下文开关（enable_log_correlation）。采样率数值越高，数据量越大。
• OAP 配置：storage 插件（选择 H2/Elasticsearch/MySQL），receiver（支持 gRPC、HTTP），以及聚合策略。
• 存储选择：本地试验可用 H2 或内存存储；生产强烈推荐 Elasticsearch 或其他支持的持久化存储来承载大量索引与查询。

组件一览（做个清单更清楚）

常见问题与排查思路（遇到问题先别慌）

• UI 无数据：确认 OAP 是否就绪（查看容器日志），Agent 的 collector 地址是否正确，网络是否可达。
• 没有 Trace：检查采样率是否被设置为 0、Agent 是否正确加载（JVM 启动日志会有 Agent 加载信息），以及应用是否使用被支持的框架自动拦截。
• 存储异常：Elasticsearch 版本兼容性常是罪魁，确认 OAP 支持的 ES 版本并查看 OAP 日志中的 Index/Mapping 错误。
• 性能问题：降低采样率、增大批量上报间隔、使用更高性能的存储后端。

生产环境的建议（别直接把本地配置搬上去）

• 开启集群模式的 OAP，避免单点瓶颈；使用专用的外部存储（Elasticsearch、ClickHouse 等）来扩展查询能力。
• 合理设置数据保留策略，分级存储热冷数据，避免占满磁盘。
• 性能考虑：Agent 端做采样、批量上报和异步上报，OAP 层做流控和限速。
• 安全与隔离：生产网络中对 gRPC/HTTP 接入做白名单与认证，防止滥用。

如何用费曼法把问题拆清楚（实际操作时的思维方式）

遇到一个看不懂的慢请求，把它像教别人一样拆解：先把“现象”描述清楚（哪个服务、哪个接口、什么时间发生），然后把“可能的原因”列出来（代码慢、数据库慢、网络慢、依赖服务慢），接着一项项验证（看 trace 里每段耗时、看数据库慢查询、抓包或看实例指标），最后归纳出可执行的修复步骤并验证效果。把每步都写下来，方便复现与回溯。

一些实用小贴士（边做边想的那种真实感）

• 测试阶段用 H2 或内嵌存储最快，但别把它当成长期方案。
• 刚开始把采样率开高一点，好看清问题；等稳定后再下调，节约存储。
• 如果使用容器化部署，把 agent 的 jar 放到镜像中或通过 sidecar 注入都行，注意和容器启动命令配合。
• 遇到 UI 看不到 topology 的情况，服务名冲突或实例心跳问题比较常见，检查实例上报的信息。

继续深入：有价值的场景与操作清单

• 查单次请求耗时分布：使用 Trace 的 Span 列表，定位慢点并展开关联依赖。
• 做服务健康监控：用 Metrics 看错误率、响应时间 p95/p99，并结合告警规则。
• 回溯故障时间窗：按时间筛选 traces，把集中出现的异常串起来看调用链共性。
• 版本回滚验证：对比不同版本的调用链图、耗时和吞吐，验证性能回退点。

如果你想继续玩深一点，参考“Apache SkyWalking 官方文档”里关于 storage、cluster、collector plugin 的章节，再结合线上数据量做性能压测。总之，先把 HelloWorld 跑通再扩，过程里多记录假设与验证，问题就会变得可管理。就先写到这儿，边做边改，说不定你会在调试时发现更好用的配置。