HelloWorld Zipkin 集成教程

在 HelloWorld 应用中接入 Zipkin，关键是把追踪上下文从入口传到每个调用点：引入 Zipkin/Brave 客户端或 Spring Cloud Sleuth，配置采样率与上报地址，在控制器、过滤器或拦截器创建并传递 span，记录关键操作与外部调用，启动 Zipkin 后端验证链路即可看到端到端追踪。

先说个直观的比喻（为什么要做）

想象你在城市里追踪一辆包裹的路程：每经过一个分拣点，就贴一个时间标签和备注。Zipkin 就是这套记录系统，应用内每一次请求或调用相当于包裹经过的站点，span 就是标签。把这些标签串起来，你就能看清一条请求从入口到出口的完整路线，发现延迟和瓶颈。

高层概念与术语（简单到能教别人）

• Trace：一次端到端请求的完整记录（相当于包裹行程）。
• Span：Trace 中的单个操作或阶段（一个分拣点），包含开始时间、持续时间、标签（tags）和日志（annotations）。
• Trace ID / Span ID：唯一标识，用于把若干 span 串成一条链路。
• Context propagation：把 trace 信息从一个服务传到下一个服务（通常通过 HTTP header 或 RPC metadata）。
• Sampler：决定哪些请求被采样并上传到 Zipkin，采样率决定成本与可见性。

准备工作（你需要什么）

• 一个 HelloWorld 应用（示例将以 Spring Boot 为主，也会给出 Node.js/Go 的思路）。
• Zipkin 后端（你可以用本地 Docker 镜像或托管服务）。
• Zipkin 客户端库：Spring Cloud Sleuth（对 Spring Boot 最友好）、Brave（Java）、zipkin-js（Node.js）、zipkin-go 等。
• 了解如何在应用里传递 HTTP header（比如 B3 header 或 W3C Trace Context）。

Zipkin 后端快速部署（最简单的本地方式）

最常见也是最快的方法是用 Docker 启动 Zipkin：一行命令就能让你立刻看到 UI 和接收器。这里略写思路，实际命令可以参考 Zipkin 官方镜像说明。注意，如果是在生产或共享环境，考虑存储（MySQL、elasticsearch）和认证。

推荐的本地调试步骤

• 用 Zipkin 自带的内存存储做快速验证。
• 需要长期保存或更大吞吐时，换成 elasticsearch 或 Cassandra。
• 在容器或云环境，要配置资源限制和持久化。

在 Spring Boot HelloWorld 中集成 Zipkin（最常见场景）

如果你的 HelloWorld 是 Spring Boot，使用 Spring Cloud Sleuth 是最省心的方式。它会自动帮你打点并把 trace header 传递给下游请求。

依赖（Maven）

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-zipkin</artifactId>
</dependency>

配置（application.yml / application.properties）

在控制器、RestTemplate、Feign 等处，Sleuth 会自动注入 Trace 信息。举个简单的 Controller：

@RestController
public class HelloController {
  @GetMapping("/hello")
  public String hello() {
    // Sleuth 会在上下文中创建 span 并记录时间
    return "Hello World";
  }
}

显式创建与记录 Span（认为你可能想记录数据库调用）

@Autowired Tracer tracer;

public void doWork() {
  Span newSpan = tracer.nextSpan().name("db-query").start();
  try (Tracer.SpanInScope ws = tracer.withSpan(newSpan.start())) {
    // 执行数据库逻辑
    newSpan.tag("db.statement", "select * from users where id=?");
  } finally {
    newSpan.finish();
  }
}

这个模式在你要记录非 HTTP 的内部操作时很有用：手动开启 span、加 tag、加 log、结束 span。

不使用 Spring？用 Brave 手动集成（更底层的 Java 方案）

如果不是 Spring Boot，Brave 是 Zipkin 的 Java 客户端库，负责创建 span、注入/提取 header、上报到 Zipkin。流程：初始化 Tracing 对象 → 在入口处提取 context → 创建新的 span → 注入 header 到下游请求 → 把 span 上报。

Tracing tracing = Tracing.newBuilder()
  .localServiceName("hello-service")
  .spanReporter(AsyncReporter.create(URLConnectionSender.create("http://localhost:9411/api/v2/spans")))
  .build();

Tracer tracer = tracing.tracer();
TraceContext context = ... // extract from incoming headers
Span span = tracer.nextSpan(context).name("handle").start();
try {
  // do work
} finally {
  span.finish();
}

Node.js / Go 的简单思路

不同语言的库名称不一样（zipkin-js、zipkin-go），但是核心流程一致：初始化 tracer → 提取 incoming trace header → 创建 span → 注入 header 到 outgoing 请求 → 上报。下面给出 Node.js 的伪代码例子：

// 使用 zipkin-js 的伪代码
const tracer = new Tracer({ctxImpl, recorder: new HttpLogger({endpoint: 'http://localhost:9411/api/v2/spans'})});
app.get('/hello', (req, res) => {
  const childId = tracer.createChildId();
  tracer.letId(childId, () => {
    tracer.recordServiceName('hello-service');
    tracer.recordAnnotation(new Annotation.ServerRecv());
    // do work
    tracer.recordAnnotation(new Annotation.ServerSend());
    res.send('ok');
  });
});

验证你的追踪是否生效（实践步骤）

• 启动 Zipkin 后端并打开 Zipkin UI（默认端口 9411），发起 /hello 请求，搜索服务名或 Trace ID。
• 检查是否出现多个 span 串成链：入口 span、外部 HTTP 调用 span、数据库 span 等。
• 如果没有看到，检查采样率、上报地址、客户端是否真的上报（可用抓包或日志）。

常见问题与排查方法

• 没有 trace 或只有部分 span：通常是 header 没有正确传递，确认上下游使用同一套 header（B3 或 W3C）。
• 采样太低：开发环境把采样率调高或 1.0，生产按容量设置；注意采样会影响统计准确性。
• 高延迟或过多上报：检查 reporter 配置，使用异步批量上报（AsyncReporter），不要在主线程同步上报。
• Trace ID 突然断开：确认负载均衡、代理或网关没有丢失或修改 trace header。

性能、成本与采样策略

Trace 数据量会很快增长，设计采样策略很重要。常见策略：

• 固定率采样（例如 0.01），适合高吞吐量服务。
• 基于错误或慢请求的采样：优先采集错误或超过阈值的请求。
• 动态采样：根据服务负载动态调整采样率。

实践建议：生产环境最低设置一个基础采样率，同时保留针对错误和关键路径的强制采样，确保问题可追溯。

标签（tags）、日志（annotations）与 Baggage

合理使用 tags 能让搜索更有意义，比如添加 endpoint、userId、orderId 等业务相关信息。但也要避免把敏感信息或过大 payload 放入 tags。Baggage 可以跨服务携带少量元数据，但滥用会增加 header 大小，影响性能。

安全性与隐私注意

• 不要在 span tag 或 logs 中记录明文密码、PII（个人身份信息）或完整请求体。
• 如果 Zipkin 部署在公网，启用认证和 TLS，或者只在受控网络内暴露。

示例配置速览（把关键点放一起）

逐步排错小清单（遇到问题快查）

• 确认客户端是否启用并指向正确的 Zipkin URL。
• 使用抓包工具或日志查看 HTTP header（是否包含 X-B3-TraceId 等）。
• 在本地把采样率调为 1.0，确认是不是采样导致看不到 trace。
• 查看 Zipkin 后端日志，确认是否有接收到 span 并成功存储。
• 检查代理、网关是否过滤或修改了 trace header。

实践小贴士（那些容易忽视的点）

• 在异步执行或线程池中要显式传递上下文（很多库提供包装器或 hook 来自动传递）。
• 给 span 合理命名，避免 generic name（如“http”），方便在 UI 中识别。
• 在关键路径加上有意义的 tag（例如 downstream 服务名、SQL hash），利于快速定位。

你可能会想做的扩展

• 将日志与 trace 关联（log correlation）：把 traceId 注入到日志上下文，方便从日志定位 trace。
• 把 Zipkin 数据导入分析系统（例如自定义指标或 APM）用于长期趋势分析。
• 结合分布式限流与熔断策略，把 tracing 数据作为熔断策略的输入。

如果你跟着上面的步骤走：先把 Zipkin 后端启动起来，再在 HelloWorld 应用里引入适合你语言的客户端，配置好采样和上报，确保 header 在调用链中不丢失，然后逐步把关键点手动打成 span，你就能看到第一条端到端的 trace。做几次后，哪些地方该自动化、哪些该手动、哪些该只写 tag，会逐渐清晰起来，调优也会更有的放矢。