openzipkin/zipkin-builder

Zipkin

镜像概述和主要用途

Zipkin是一款分布式追踪系统，用于收集服务架构中排查延迟问题所需的时序数据，支持数据的收集与查询功能。通过日志中的跟踪ID可直接定位相关跟踪数据，也可基于服务名、操作名、标签、持续时间等属性进行查询，并汇总展示服务耗时占比、操作失败情况等关键数据。其UI还提供依赖关系图，直观展示跟踪请求流经的应用，帮助识别聚合行为（如错误路径或 deprecated 服务调用）。

!跟踪视图截图

!依赖关系图截图

应用需通过跟踪器或 instrumentation 库配置以上报跟踪数据，支持HTTP、Kafka、Apache ActiveMQ、gRPC、RabbitMQ等多种上报方式。UI展示的数据可存储在内存中，或通过Apache Cassandra、Elasticsearch等后端持久化存储。

核心功能和特性

• 数据收集与查询：支持通过跟踪ID直接定位数据，或通过服务、操作名、标签、持续时间等属性筛选查询。
• 可视化展示：UI展示跟踪详情（如耗时分布、失败率）和服务依赖关系图，直观呈现服务调用路径。
• 多上报方式：兼容HTTP、Kafka、ActiveMQ、gRPC、RabbitMQ等多种跟踪数据上报渠道。
• 灵活存储：支持内存存储（测试用）及Cassandra、Elasticsearch等持久化存储后端。
• 搜索功能：默认启用服务、操作名、标签等搜索端点，可禁用以降低存储成本或提升写入吞吐量。

使用场景和适用范围

• 服务架构延迟排查：收集服务间调用时序数据，定位 latency 问题根源。
• 服务依赖分析：通过依赖图识别服务调用路径、错误路径或 deprecated 服务调用。
• 跟踪数据查询：通过日志中的跟踪ID快速关联跟踪记录，或通过属性筛选特定跟踪数据。
• 分布式系统监控：汇总服务耗时占比、失败率等指标，辅助系统性能优化。

详细使用方法和配置说明

快速启动

Docker 部署

使用Docker快速启动Zipkin服务：

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

服务启动后，通过 http://你的主机IP:9411/zipkin/ 访问Zipkin UI。

JAR包启动（需JRE 8+）

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

配置说明

存储后端配置

• 内存存储：默认方式，非持久化，适用于本地测试，无需数据库依赖。
• Apache Cassandra：需配置Cassandra主机（如CASSANDRA_CONTACT_POINTS=host1,host2），支持大规模数据，依赖https://github.com/openzipkin/zipkin-dependencies%E4%BB%BB%E5%8A%A1%E8%81%9A%E5%90%88%E4%BE%9D%E8%B5%96%E5%85%B3%E7%B3%BB%E3%80%82
• Elasticsearch：需配置Elasticsearch主机（如ES_HOSTS=http://host:9200），支持5+版本，依赖https://github.com/openzipkin/zipkin-dependencies%E8%81%9A%E5%90%88%E4%BE%9D%E8%B5%96%E5%85%B3%E7%B3%BB%E3%80%82

禁用搜索功能

默认启用以下搜索端点（支持UI跟踪列表页功能）：

• GET /services：获取 distinct Span.localServiceName
• GET /remoteServices?serviceName=X：按本地服务名获取 distinct Span.remoteServiceName
• GET /spans?serviceName=X：按本地服务名获取 distinct Span.name
• GET /autocompleteKeys：获取 Span.tags 中白名单内的 distinct 键
• GET /autocompleteValues?key=X：按键获取 Span.tags 的 distinct 值
• GET /traces：按上述条件筛选跟踪记录

禁用搜索后，仅允许通过跟踪ID查询（GET /trace/{traceId}），适用于通过日志获取跟踪ID的场景。可通过环境变量禁用：

bash
docker run -d -p 9411:9411 -e SEARCH_ENABLED=false openzipkin/zipkin

或代码配置：StorageComponent.Builder.searchEnabled(false)。

存储组件详情

内存存储（In-Memory）

包含在核心库中，非持久化，不适合生产环境，仅用于测试（如本地启动服务器无需数据库）。

Apache Cassandra

• 要求：Cassandra 3.11.3+，测试基于最新3.11.x补丁版本。
• 特性：第二代schema，使用UDT存储span（类似Zipkin v2 JSON格式），结合SASI和手动索引优化大规模数据查询性能。
• 注意：需通过https://github.com/openzipkin/zipkin-dependencies%E4%BB%BB%E5%8A%A1%E8%81%9A%E5%90%88%E4%BE%9D%E8%B5%96%E5%85%B3%E7%B3%BB%E3%80%82

Elasticsearch

• 要求：Elasticsearch 5+，测试支持6-7.x版本。
• 特性：以Zipkin v2 JSON格式存储span，便于与其他工具集成，结合自定义和手动索引优化规模。
• 注意：需通过https://github.com/openzipkin/zipkin-dependencies%E8%81%9A%E5%90%88%E4%BE%9D%E8%B5%96%E5%85%B3%E7%B3%BB%E3%80%82

遗留组件（v1）

基于Zipkin V1 Thrift模型，不推荐新使用，仅用于过渡：

• MySQL v1：支持MySQL 5.6+（MariaDB 10.3测试通过），schema设计简单但存在性能问题，大规模数据查询延迟高。依赖聚合任务生成依赖图（可选，运行任务可提升查询性能）。
• Cassandra v1：支持Cassandra 2.2+，基于***原始schema，span存储为 opaque thrifts（cqlsh无法查询字段），需通过https://github.com/openzipkin/zipkin-dependencies%E4%BB%BB%E5%8A%A1%E8%81%9A%E5%90%88%E4%BE%9D%E8%B5%96%E5%85%B3%E7%B3%BB%E3%80%82

从源码运行服务器

需JDK 11编译源码：

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

镜像和 artifacts 信息

• Docker镜像：发布版本推送到Docker Hub openzipkin/zipkin，详情见https://github.com/openzipkin/docker-zipkin%E3%80%82
• Maven坐标：服务器 artifacts groupId io.zipkin，核心库 artifacts groupId io.zipkin.zipkin2。
• 发布渠道：Releases同步到Maven Central，Snapshots发布到JFrog，Javadocs见[***]