zipkin-dependencies

镜像概述和主要用途

Zipkin Dependencies 是一个 Apache Spark 作业，用于从存储中收集跟踪数据（spans），分析服务之间的依赖关系，并将结果存储起来以便在 Web UI 中展示（例如：http://localhost:8080/dependency）。

该作业会解析 UTC 时间当天的所有跟踪数据，因此应安排在接近 UTC 时间午夜前运行。支持所有 Zipkin 存储组件，包括 Cassandra、MySQL 和 Elasticsearch。

核心功能和特性

• 通过 Spark 作业分析服务间依赖关系
• 支持多种存储后端（Cassandra、MySQL、Elasticsearch）
• 可配置的日期范围分析
• 兼容多种安全认证机制
• 灵活的 Spark 集群配置选项

使用场景和适用范围

Zipkin Dependencies 适用于需要可视化和分析分布式系统中服务间调用关系的场景，特别是在微服务架构环境中。它能够帮助开发和运维团队理解系统拓扑结构，识别性能瓶颈和故障点。

版本支持

• STORAGE_TYPE=cassandra3：需要 Cassandra 3.11.3+；已针对 3.11 的最新补丁版本测试
• STORAGE_TYPE=cassandra：需要 Cassandra 2.2+；已针对 3.11 的最新补丁版本测试
• STORAGE_TYPE=mysql：需要 MySQL 5.6+；已针对 MySQL 5.6 测试
• STORAGE_TYPE=elasticsearch：需要 Elasticsearch 5+；已针对 6.x 和 7.x 的最新次要版本测试

快速开始

由于 SPARK-26134 问题，Zipkin Dependencies 当前需要 Java 1.8 或 9 运行环境。

通过 JAR 文件运行

# 下载最新版本的 JAR 文件
$ curl -sSL [***] | bash -s io.zipkin.dependencies:zipkin-dependencies:LATEST zipkin-dependencies.jar

# 使用 Cassandra3 存储运行
$ STORAGE_TYPE=cassandra3 java -jar zipkin-dependencies.jar

通过 Docker 运行

$ docker run --env STORAGE_TYPE=cassandra3 --env CASSANDRA_CONTACT_POINTS=host1,host2 openzipkin/zipkin-dependencies

使用方法

默认情况下，作业会解析从 UTC 时间午夜开始的所有跟踪数据。您可以通过指定 YYYY-mm-dd 格式的参数来分析不同日期的数据：

# 在 OS/X 上处理昨天的跟踪数据
$ STORAGE_TYPE=cassandra3 java -jar zipkin-dependencies.jar `date -uv-1d +%F`

# 在 Linux 上处理昨天的跟踪数据
$ STORAGE_TYPE=cassandra3 java -jar zipkin-dependencies.jar `date -u -d '1 day ago' +%F`

环境变量

zipkin-dependencies 通过环境变量应用配置参数。以下变量适用于所有存储层：

• SPARK_MASTER：提交作业的 Spark master；默认为 local[*]
• ZIPKIN_LOG_LEVEL：Zipkin 相关状态的日志级别；默认为 INFO（使用 DEBUG 获取详细信息）
• SPARK_CONF：以属性格式扩展更多 Spark 配置，用逗号分隔。例如：spark.executor.heartbeatInterval=600000,spark.network.timeout=600000

Cassandra 存储

当 STORAGE_TYPE=cassandra 或 STORAGE_TYPE=cassandra3 时使用 Cassandra：

• cassandra 兼容 Zipkin 的 Legacy Cassandra 存储组件
• cassandra3 兼容 Zipkin 的 Cassandra v3 存储组件

相关环境变量：

• CASSANDRA_KEYSPACE：使用的 keyspace；默认为 "zipkin"
• CASSANDRA_CONTACT_POINTS：Cassandra 集群的主机/IP 地址列表，用逗号分隔；默认为 localhost
• CASSANDRA_LOCAL_DC：要连接的本地数据中心（将忽略其他节点）
• CASSANDRA_USERNAME 和 CASSANDRA_PASSWORD：Cassandra 认证信息；认证失败时会在启动时抛出异常
• CASSANDRA_USE_SSL：是否使用 SSL，需要配置 javax.net.ssl.trustStore 和 javax.net.ssl.trustStorePassword；默认为 false
• STRICT_TRACE_ID：设为 false 时，依赖链接仅查看 trace ID 的 64 位；默认为 true

示例用法：

$ STORAGE_TYPE=cassandra3 CASSANDRA_USERNAME=user CASSANDRA_PASSWORD=pass java -jar zipkin-dependencies.jar

Docker 示例：

$ docker run --env STORAGE_TYPE=cassandra3 \
             --env CASSANDRA_CONTACT_POINTS=host1,host2 \
             --env CASSANDRA_USERNAME=user \
             --env CASSANDRA_PASSWORD=pass \
             openzipkin/zipkin-dependencies

MySQL 存储

当 STORAGE_TYPE=mysql 时使用 MySQL，其 schema 兼容 Zipkin 的 MySQL 存储组件。

相关环境变量：

• MYSQL_DB：使用的数据库；默认为 "zipkin"
• MYSQL_USER 和 MYSQL_PASS：MySQL 认证信息；默认为空字符串
• MYSQL_HOST：MySQL 主机；默认为 localhost
• MYSQL_TCP_PORT：MySQL 端口；默认为 3306
• MYSQL_USE_SSL：是否使用 SSL，需要配置 javax.net.ssl.trustStore 和 javax.net.ssl.trustStorePassword；默认为 false

示例用法：

$ STORAGE_TYPE=mysql MYSQL_USER=root java -jar zipkin-dependencies.jar

Docker 示例：

$ docker run --env STORAGE_TYPE=mysql \
             --env MYSQL_HOST=mysql-host \
             --env MYSQL_USER=root \
             --env MYSQL_PASS=secret \
             openzipkin/zipkin-dependencies

Elasticsearch 存储

当 STORAGE_TYPE=elasticsearch 时使用 Elasticsearch，其 schema 兼容 Zipkin 的 Elasticsearch 存储组件。

相关环境变量：

• ES_INDEX：生成每日索引名称时使用的前缀；默认为 zipkin
• ES_DATE_SEPARATOR：生成索引日期时使用的分隔符；默认为 '-'，查询的索引类似 zipkin-yyyy-DD-mm；可改为 '.' 生成 zipkin-yyyy.MM.dd
• ES_HOSTS：Elasticsearch HTTP 主机的逗号分隔列表；默认为 localhost。如果不是监听 9200 端口，请添加端口部分。集群中只需有一个主机可用即可获取集群中的其余节点。建议设置为集群的所有主节点。对于 SSL，请使用 URL 格式，例如："[***]"
• ES_NODES_WAN_ONLY：设为 true 时仅使用 ES_HOSTS 中设置的值，例如当 Elasticsearch 集群在 Docker 中时；默认为 false
• ES_USERNAME 和 ES_PASSWORD：Elasticsearch 基本认证信息，当使用 X-Pack 安全（以前的 Shield）时使用；默认不提供用户名或密码

示例用法：

$ STORAGE_TYPE=elasticsearch ES_HOSTS=host1,host2 java -jar zipkin-dependencies.jar

# 要覆盖 HTTP 端口，请将其添加到主机字符串中
$ STORAGE_TYPE=elasticsearch ES_HOSTS=host1:9201 java -jar zipkin-dependencies.jar

Docker 示例：

$ docker run --env STORAGE_TYPE=elasticsearch \
             --env ES_HOSTS=[***] \
             --env ES_USERNAME=elastic \
             --env ES_PASSWORD=changeme \
             openzipkin/zipkin-dependencies

自定义证书

当在 ES_HOSTS 中使用 https 端点时，可以使用以下标准属性来自定义连接使用的证书：

• javax.net.ssl.keyStore
• javax.net.ssl.keyStorePassword
• javax.net.ssl.trustStore
• javax.net.ssl.trustStorePassword

本地构建

从源代码构建作业并在 Spark 独立模式下针对本地 Cassandra 运行：

# 构建 Spark 作业
$ ./mvnw -q --batch-mode -DskipTests -Denforcer.fail=false --also-make -pl main package

# 运行作业
$ STORAGE_TYPE=cassandra java -jar ./main/target/zipkin-dependencies*.jar

在 Spark 集群中运行

此构建生成的 jar 文件也可以直接在 Spark 上运行。首先，请确保您运行的 Spark 版本与此处使用的版本相同。

您可以使用以下命令显示此项目构建所针对的 Spark 版本：

$ SPARK_VERSION=$(./mvnw help:evaluate -Dexpression=spark.version -q -DforceStdout)
$ echo $SPARK_VERSION
2.4.0

验证设置使用正确版本后，设置 SPARK_MASTER 变量：

例如，如果连接到同一主机上运行的 Spark：

$ STORAGE_TYPE=cassandra3 SPARK_MASTER=spark://$HOSTNAME:7077 java -jar zipkin-dependencies.jar

注意：Zipkin 团队专注于跟踪功能，而非 Spark 支持。如果您有 Spark 集群相关的故障排除问题，请使用 Spark 的 支持工具。

故障排除

排查问题时，请始终设置 ZIPKIN_LOG_LEVEL=DEBUG，因为此输出对于找出跟踪未生成链接的原因很重要。

如果将 SPARK_MASTER 设置为本地以外的值，请记住日志输出也会出现在工作节点的 stderr 中。

默认情况下，此作业使用系统属性 java.io.tmpdir 的值作为存储临时数据的位置。如果在处理大量跟踪数据时遇到 java.io.IOException: No space left on device，可以使用 -Djava.io.tmpdir=/other/location 指定有足够空间的其他位置。

制品信息

所有制品发布到组 ID "io.zipkin.dependencies"。我们对所有组件使用通用的发布版本。

库发布版本

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

库快照版本

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