Zipkin

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

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

Zipkin UI 还提供依赖图，展示有多少跟踪请求经过了每个应用。这有助于识别聚合行为，包括错误路径或对已弃用服务的调用。

应用需要进行“ instrumentation”（即 instrumentation 配置）才能向 Zipkin 报告跟踪数据。这通常意味着需要配置追踪器或 instrumentation 库。向 Zipkin 报告数据最常用的方式是通过 HTTP 或 Kafka，但也存在许多其他选项，如 Apache ActiveMQ、gRPC 和 RabbitMQ。提供给 UI 的数据可以存储在内存中，或通过受支持的后端（如 Apache Cassandra 或 Elasticsearch）持久化存储。

快速启动

最快速的启动方式是获取最新发布的服务器作为独立可执行 JAR 文件。注意，Zipkin 服务器需要至少 JRE 8 环境。例如：

bash
curl -sSL [***] | bash -s
java -jar zipkin.jar

你也可以通过 Docker 启动 Zipkin：

bash
docker run -d -p 9411:9411 openzipkin/zipkin

服务器启动后，你可以通过 Zipkin UI 在 [***] 查看跟踪数据。

如果你的应用尚未发送跟踪数据，请使用Zipkin instrumentation 进行配置，或尝试我们的示例。

有关配置详情，请查看 zipkin-server 文档，或参考 docker-zipkin 了解如何使用 docker-compose。

核心库

核心库 供 Zipkin instrumentation 和 Zipkin 服务器使用。其最低支持 Java 6 语言级别，以支持编写代理 instrumentation。

该库包含 Zipkin v1 和 v2 JSON 格式的内置编解码器。通过精简和重新打包所用类，避免了对 gson（JSON 库）的直接依赖。生成的 JAR 包大小为 155k，不会与你使用的任何库冲突。

示例：

java
// 所有数据都记录在同一个端点，与你的服务图关联
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。

存储组件

Zipkin 包含 StorageComponent，用于存储和查询跨度（span）及依赖链接。服务器、收集器或跨度报告器都会用到它。因此，存储组件的依赖极少，但大多数需要 Java 8+ 环境。

示例：

java
// 此操作不会创建网络连接
storage = ElasticsearchStorage.newBuilder()
                              .hosts(asList("[***]")).build();

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

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

// 清理会话等资源
storage.close();

内存存储

InMemoryStorage 组件打包在 Zipkin 核心库中。它既不持久化数据，也不适用于实际工作负载。其用途是测试，例如在笔记本电脑上启动服务器而无需任何数据库。

Cassandra

Cassandra 组件使用 Cassandra 3.11.3+ 特性，但会针对最新的 Cassandra 3.11 补丁版本进行测试。

这是我们的第二代 Cassandra 模式。它使用 UDT 存储跨度，因此在 cqlsh 中看起来类似 Zipkin v2 JSON。其设计考虑了可扩展性，并结合使用 SASI 和手动实现的索引，使查询大量数据时更高效。

注意：此存储需要通过作业聚合依赖链接。

Elasticsearch

Elasticsearch 组件使用 Elasticsearch 5+ 特性，但会针对 Elasticsearch 6-7.x 进行测试。

它将跨度存储为 Zipkin v2 JSON，以便与其他工具集成。为帮助扩展，它结合使用自定义索引和手动实现的索引。

注意：此存储需要通过Spark 作业聚合依赖链接。

禁用搜索

以下 API 端点提供搜索功能，默认启用。搜索主要用于 UI 的跟踪列表页面。

• GET /services - distinct Span.localServiceName
• GET /remoteServices?serviceName=X - 按 Span.localServiceName 筛选的 distinct Span.remoteServiceName
• GET /spans?serviceName=X - 按 Span.localServiceName 筛选的 distinct Span.name
• GET /autocompleteKeys - 受配置白名单限制的 Span.tags 键的 distinct 值
• GET /autocompleteValues?key=X - 按键筛选的 Span.tags 值的 distinct 值
• GET /traces - 匹配包含上述条件的查询的跟踪数据

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

当 Zipkin 通过环境变量 SEARCH_ENABLED=false 运行时，会隐含 StorageComponent.Builder.searchEnabled(false)。

遗留（v1）组件

以下组件不再推荐使用，但为过渡到受支持的组件提供帮助。这些组件标为“v1”，因为它们使用基于 Zipkin V1 Thrift 模型的数据布局，而非当前使用的更简单的 v2 数据模型。

MySQL

MySQL v1 组件使用 MySQL 5.6+ 特性，但会针对 MariaDB 10.3 进行测试。

该模式设计易于理解和上手，但并非为性能而设计。例如，跨度字段作为列，因此你可以使用 SQL 执行临时查询。然而，此组件存在已知性能问题：如果存入大量数据，查询最终会耗时数秒。

此存储不需要通过作业聚合依赖链接。但运行作业可提高依赖查询的性能。

Cassandra

Cassandra v1 组件使用 Cassandra 2.2+ 特性，但会针对最新的 Cassandra 3.11 补丁版本进行测试。

CQL 编写于 2015 年，基于 *** 的原始 Cassandra 模式，并经过扩展。跨度存储为不透明的 Thrift 数据，这意味着你无法在 cqlsh 中查询字段。该模式为可扩展性而设计，包括手动实现的索引，使查询大量数据时更高效。

注意：此存储需要通过作业聚合依赖链接。

从源码运行服务器

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

要从当前检出的源码运行服务器，请执行以下命令。编译源码需要 JDK 11。

bash
# 构建服务器及其依赖
$ ./mvnw -DskipTests --also-make -pl zipkin-server clean install
# 运行服务器
$ java -jar ./zipkin-server/target/zipkin-server-*exec.jar

制品

服务器制品的 Maven groupId 为 io.zipkin，库制品的 Maven groupId 为 io.zipkin.zipkin2。

库发布版本

发布版本上传至 Bintray 并同步至 Maven Central。

库快照版本

提交至 master 分支后，快照版本上传至 JFrog。

Docker 镜像

zipkin-server 的发布版本发布至 Docker Hub，镜像名为 openzipkin/zipkin。详情参见 docker-zipkin。

Javadocs

[***] 包含版本化文件夹，其中包含每次（非 PR）构建及发布版本的 Javadoc。