zipkin

Zipkin 是一个分布式追踪系统。它有助于收集解决服务架构中延迟问题所需的时序数据。其功能包括这些数据的收集和查询。

如果你在日志文件中有一个追踪 ID，可以直接跳转到它。否则，你可以根据服务、操作名称、标签和持续时间等属性进行查询。一些有趣的数据会为你进行汇总，比如在某个服务中花费的时间百分比，以及操作是否失败。

Zipkin 的用户界面还展示了一个依赖关系图，显示有多少被追踪的请求通过了每个应用程序。这对于识别包括错误路径或对已弃用服务的调用在内的聚合行为很有帮助。

应用程序需要进行"插桩"以向 Zipkin 报告追踪数据。这通常意味着配置追踪器或插桩库。向 Zipkin 报告数据最流行的方式是通过 HTTP 或 Kafka，尽管还存在许多其他选项，如 Apache ActiveMQ、gRPC 和 RabbitMQ。提供给用户界面的数据存储在内存中，或者通过支持的后端（如 Apache Cassandra 或 Elasticsearch）持久化存储。

快速入门

最快的开始方式是获取最新发布的服务器作为独立的可执行 jar 包。注意，Zipkin 服务器至少需要 JRE 17+。例如：

curl -sSL https://zipkin.io/quickstart.sh | bash -s
java -jar zipkin.jar

你也可以通过 Docker 启动 Zipkin。

# 注意：这在 ghcr.io/openzipkin/zipkin 上有镜像
docker run -d -p 9411:9411 openzipkin/zipkin

一旦服务器运行，你可以在 http://localhost:9411/zipkin 通过 Zipkin 用户界面查看追踪。

如果你的应用程序还没有发送追踪，请使用 Zipkin 插桩配置它们，或者尝试我们的示例之一。

查看 zipkin-server 文档了解配置详情，或者查看 Docker 示例了解如何使用 docker-compose。

Zipkin Slim

Zipkin 的精简版更小且启动更快。它支持内存和 Elasticsearch 存储，但不支持像 Kafka 或 RabbitMQ 这样的消息传输。如果这些限制符合你的需求，你可以像下面这样尝试精简版：

通过 Java 运行：

curl -sSL https://zipkin.io/quickstart.sh | bash -s io.zipkin:zipkin-server:LATEST:slim zipkin.jar
java -jar zipkin.jar

通过 Docker 运行：

# 注意：这在 ghcr.io/openzipkin/zipkin-slim 上有镜像
docker run -d -p 9411:9411 openzipkin/zipkin-slim

通过 Homebrew 运行：

brew install zipkin
# 在前台运行
zipkin
# 在后台运行
brew services start zipkin

核心库

核心库被 Zipkin 插桩和 Zipkin 服务器同时使用。

这包括 Zipkin 的 v1 和 v2 json 格式的内置编解码器。通过最小化和重新打包使用的类，避免了对 gson（json 库）的直接依赖。结果是一个 155k 的 jar 包，不会与你使用的任何库冲突。

例如：

// 所有数据都记录在同一个端点上，与你的服务图关联
localEndpoint = Endpoint.newBuilder().serviceName("tweetie").ip("192.168.0.1").build()
span = Span.newBuilder()
    .traceId("d3d200866a77cc59")
    .id("d3d200866a77cc59")
    .name("targz")
    .localEndpoint(localEndpoint)
    .timestamp(epochMicros())
    .duration(durationInMicros)
    .putTag("compression.level", "9");

// 现在，你可以将其编码为 json
bytes = SpanBytesEncoder.JSON_V2.encode(span);

注意：上面只是一个例子，你很可能会想使用现有的追踪库，如 Brave

核心库需要 Java 8+

核心库的最低 Java 语言级别是 8。这有助于支持那些编写代理插桩的人。2.x 版本是最后一个支持 Java 6 的版本。

注意：zipkin-reporter-brave 不使用此库。因此，brave 仍然支持 Java 6。

存储组件

Zipkin 包含一个 StorageComponent，用于存储和查询跨度和依赖链接。这被服务器和那些制作收集器或跨度报告器的人使用。出于这个原因，存储组件的依赖最小化，但需要 Java 17+。

例如：

// 这不会创建网络连接
storage = ElasticsearchStorage.newBuilder()
                              .hosts(asList("http://myelastic:9200")).build();

// 准备一个调用
traceCall = storage.spanStore().getTrace("d3d200866a77cc59");

// 同步或异步执行
trace = traceCall.execute();

// 清理任何会话等
storage.close();

内存存储

InMemoryStorage组件已打包在zipkin的核心库中。它既不持久也不适用于实际工作负载。其目的是用于测试，例如在不需要任何数据库的情况下在笔记本电脑上启动服务器。

Cassandra存储

Cassandra组件使用Cassandra 3.11.3+的功能，但已经过Cassandra 4.1最新补丁版本的测试。

这是我们Cassandra模式的第二代。它使用UDT存储spans，使其在cqlsh中看起来像Zipkin v2 json。它设计用于大规模应用，并使用SASI和手动实现的索引组合来提高大数据查询性能。

注意：此存储需要一个作业来聚合依赖链接。

Elasticsearch存储

Elasticsearch组件使用Elasticsearch 5+的功能，但已经过Elasticsearch 7-8.x和OpenSearch 2.x的测试。

它将spans存储为Zipkin v2 json格式，使与其他工具的集成变得简单。为了帮助扩展，它使用自定义和手动实现的索引组合。

注意：此存储需要一个spark作业来聚合依赖链接。

禁用搜索

以下API端点提供搜索功能，默认情况下启用。搜索主要允许UI的跟踪列表页面操作。

GET /services - 不同的Span.localServiceName
GET /remoteServices?serviceName=X - 按Span.localServiceName区分的Span.remoteServiceName
GET /spans?serviceName=X - 按Span.localServiceName区分的Span.name
GET /autocompleteKeys - 受可配置白名单约束的不同Span.tags键
GET /autocompleteValues?key=X - 按键区分的不同Span.tags值
GET /traces - 匹配可能包含上述条件的查询的跟踪

当搜索被禁用时，只能通过ID检索跟踪（GET /trace/{traceId}）。只有在有其他方式查找跟踪ID（如日志）时，禁用搜索才可行。禁用搜索可以降低存储成本或提高写入吞吐量。

当使用环境变量SEARCH_ENABLED=false运行zipkin时，StorageComponent.Builder.searchEnabled(false)会被隐含设置。

遗留（v1）组件

以下组件不再被鼓励使用，但存在以帮助过渡到受支持的组件。这些被标记为"v1"，因为它们使用基于Zipkin的V1 Thrift模型的数据布局，而不是当前使用的更简单的v2数据模型。

MySQL

MySQL v1组件使用MySQL 5.6+的功能，但已经过MariaDB 10.11的测试。

该模式设计为易于理解和上手；它并非为性能而设计。例如，spans字段是列，因此您可以使用SQL执行临时查询。然而，此组件存在已知的性能问题：如果您向其中输入大量数据，查询最终会花费数秒才能返回结果。

此存储不需要作业来聚合依赖链接。但是，运行该作业将提高依赖查询的性能。

从源代码运行服务器

Zipkin服务器通过HTTP POST接收spans并响应来自其UI的查询。它还可以运行收集器，如RabbitMQ或Kafka。

要从当前检出的源代码运行服务器，请输入以下内容。编译源代码需要JDK 17+。

# 构建服务器并同时构建其依赖项
$ ./mvnw -q --batch-mode -DskipTests --also-make -pl zipkin-server clean install
# 运行服务器
$ java -jar ./zipkin-server/target/zipkin-server-*exec.jar