Jaeger Spark 依赖分析

这是一个 Spark 作业，用于从存储中收集追踪跨度（spans），分析服务间的链路关系，并将其存储以便后续在 UI 中展示。> [!NOTE] 生产环境部署需要此作业。all-in-one 发行版不需要此作业。

此作业基于 UTC 时间解析指定日期的所有追踪数据。默认情况下，它处理当天数据，但也可以显式指定其他日期。

快速启动

Spark 作业可以作为 Docker 容器运行，也可以作为 Java 可执行文件运行：

容器镜像变体

从 0.6.x 版本开始，Docker 镜像以特定变体标签发布。每个变体自动使用相应的存储后端，因此不再需要 STORAGE 环境变量。

镜像命名格式为 ghcr.io/jaegertracing/spark-dependencies/spark-dependencies:{VERSION}-{VARIANT}：

• VERSION-cassandra：适用于 Cassandra 存储（直接使用 CassandraDependenciesJob）
• VERSION-elasticsearch7：适用于 Elasticsearch 7.12-7.16（使用 ElasticsearchDependenciesJob 和 ES 连接器 7.17.29）
• VERSION-elasticsearch8：适用于 Elasticsearch 7.17+ 和 8.x（使用 ElasticsearchDependenciesJob 和 ES 连接器 8.13.4）
• VERSION-elasticsearch9：适用于 Elasticsearch 9.x（使用 ElasticsearchDependenciesJob 和 ES 连接器 9.1.3）—— 也标记为 :latest
• VERSION-opensearch：适用于 OpenSearch 2.x 和 3.x（使用 OpenSearchDependenciesJob 和 OpenSearch Java 客户端）

Cassandra 示例：

$ docker run \
--env CASSANDRA_CONTACT_POINTS=host1,host2 \
ghcr.io/jaegertracing/spark-dependencies/spark-dependencies:v0.5.3-cassandra

Elasticsearch 8.x 示例：

$ docker run \
--env ES_NODES=http://elasticsearch:9200 \
ghcr.io/jaegertracing/spark-dependencies/spark-dependencies:v0.5.3-elasticsearch8

OpenSearch 示例：

$ docker run \
--env OS_NODES=http://opensearch:9200 \
ghcr.io/jaegertracing/spark-dependencies/spark-dependencies:v0.5.3-opensearch

高级配置

使用 --env JAVA_OPTS 传递额外的 Java 选项，例如内存设置、SSL 信任库或其他 JVM 属性：

# 示例：配置 SSL 信任库
$ docker run \
--env ES_NODES=https://elasticsearch:9200 \
--env JAVA_OPTS="-Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=changeit" \
ghcr.io/jaegertracing/spark-dependencies/spark-dependencies:v0.5.3-elasticsearch8

# 示例：增加 JVM 堆大小
$ docker run \
--env OS_NODES=http://opensearch:9200 \
--env JAVA_OPTS="-Xmx2g -Xms1g" \
ghcr.io/jaegertracing/spark-dependencies/spark-dependencies:v0.5.3-opensearch

使用 --env LOG4J_STATUS_LOGGER_LEVEL 控制 Log4j2 内部状态消息（默认值为 OFF）：

# 示例：启用 Log4j2 调试日志以进行故障排查
$ docker run \
--env OS_NODES=http://opensearch:9200 \
--env LOG4J_STATUS_LOGGER_LEVEL=DEBUG \
ghcr.io/jaegertracing/spark-dependencies/spark-dependencies:v0.5.3-opensearch

[!NOTE] 最新版本托管在 ghcr.io 上，而非 Docker Hub。

作为 JAR 文件：

STORAGE=cassandra java -jar jaeger-spark-dependencies.jar

使用方法

默认情况下，此作业解析自 UTC 午夜起的所有追踪数据。您可以通过 YYYY-mm-dd 格式的参数（如 2016-07-16）解析其他日期的追踪数据，或通过环境属性指定日期。

# 示例：在 OS/X 上运行作业以处理昨天的追踪数据
$ STORAGE=cassandra java -jar jaeger-spark-dependencies.jar `date -uv-1d +%F`
# 或在 Linux 上
$ STORAGE=cassandra java -jar jaeger-spark-dependencies.jar `date -u -d '1 day ago' +%F`

配置

jaeger-spark-dependencies 通过环境变量应用配置参数。

以下变量适用于所有存储层：

• SPARK_MASTER：提交作业的 Spark 主节点；默认为 local[*]
• DATE：YYYY-mm-dd 格式的日期。表示将为其创建依赖链路的日期。
• PEER_SERVICE_TAG：用于在跨度中标识对等服务的标签名称。默认为 peer.service
• JAVA_OPTS：传递给 JVM 的额外 Java 选项。用于配置内存、SSL 属性或其他 JVM 设置。示例：JAVA_OPTS="-Xmx2g -Djavax.net.ssl.trustStore=/path/to/truststore"。> [!NOTE] Java 21+ 上运行 Spark 所需的 --add-opens 标志已包含在容器镜像中。
• LOG4J_STATUS_LOGGER_LEVEL：Log4j2 StatusLogger 级别。默认为 OFF 以抑制 Log4j2 内部状态消息。如果需要调试日志配置问题，可设置为 TRACE、DEBUG、INFO、WARN、ERROR 或 FATAL。

Cassandra

当 STORAGE=cassandra 时使用 Cassandra。

• CASSANDRA_KEYSPACE：要使用的键空间。默认为 "jaeger_v1_dc1"。
• CASSANDRA_CONTACT_POINTS：Cassandra 集群中的主机/IP 地址列表，以逗号分隔。默认为 localhost
• CASSANDRA_LOCAL_DC：要连接的本地数据中心（其他节点将被忽略）
• CASSANDRA_USERNAME 和 CASSANDRA_PASSWORD：Cassandra 身份验证。如果身份验证失败，启动时将抛出异常
• CASSANDRA_USE_SSL：需要 javax.net.ssl.trustStore 和 javax.net.ssl.trustStorePassword，默认为 false。
• CASSANDRA_CLIENT_AUTH_ENABLED：如果设置，将在 SSL 连接上启用客户端身份验证。需要 javax.net.ssl.keyStore 和 javax.net.ssl.keyStorePassword，默认为 false。

使用示例：

$ STORAGE=cassandra CASSANDRA_CONTACT_POINTS=localhost:9042 java -jar jaeger-spark-dependencies.jar

Elasticsearch

当 STORAGE=elasticsearch 时使用 Elasticsearch。

[!IMPORTANT] 请为您的 Elasticsearch 版本使用相应的 Docker 镜像变体：

• ES 7.12-7.16：使用 :VERSION-elasticsearch7 标签
• ES 7.17-8.x：使用 :VERSION-elasticsearch8 标签
• ES 9.x：使用 :VERSION-elasticsearch9 标签（或 :latest）

配置

本地构建

要在本地构建作业并运行测试：

./mvnw clean install # 若失败，添加 SPARK_LOCAL_IP=127.0.0.1

要运行统一JAR（包含所有依赖）：

STORAGE=cassandra java -jar jaeger-spark-dependencies/target/jaeger-spark-dependencies-0.0.1-SNAPSHOT.jar
# 或
STORAGE=elasticsearch ES_NODES=http://localhost:9200 java -jar jaeger-spark-dependencies/target/jaeger-spark-dependencies-0.0.1-SNAPSHOT.jar
# 或
STORAGE=opensearch OS_NODES=http://localhost:9200 java -jar jaeger-spark-dependencies/target/jaeger-spark-dependencies-0.0.1-SNAPSHOT.jar

要直接运行特定存储的JAR（无需STORAGE变量）：

# Cassandra
java -jar jaeger-spark-dependencies-cassandra/target/jaeger-spark-dependencies-cassandra-0.0.1-SNAPSHOT.jar
# Elasticsearch
ES_NODES=http://localhost:9200 java -jar jaeger-spark-dependencies-elasticsearch/target/jaeger-spark-dependencies-elasticsearch-0.0.1-SNAPSHOT.jar
# OpenSearch
OS_NODES=http://localhost:9200 java -jar jaeger-spark-dependencies-opensearch/target/jaeger-spark-dependencies-opensearch-0.0.1-SNAPSHOT.jar

构建Docker镜像：

[!NOTE] Dockerfile现在需要预构建的JAR。请先使用Maven构建JAR，然后再构建Docker镜像。

对于Cassandra：

./mvnw clean package --batch-mode -Dlicense.skip=true -DskipTests -pl jaeger-spark-dependencies-cassandra -am
mkdir -p artifact-target
cp jaeger-spark-dependencies-cassandra/target/jaeger-spark-dependencies-cassandra-0.0.1-SNAPSHOT.jar artifact-target/
docker build --build-arg VARIANT=cassandra -t jaegertracing/spark-dependencies:cassandra .

对于Elasticsearch 9：

./mvnw clean package --batch-mode -Dlicense.skip=true -DskipTests -Dversion.elasticsearch.spark=9.1.3 -pl jaeger-spark-dependencies-elasticsearch -am
mkdir -p artifact-target
cp jaeger-spark-dependencies-elasticsearch/target/jaeger-spark-dependencies-elasticsearch-0.0.1-SNAPSHOT.jar artifact-target/
docker build --build-arg VARIANT=elasticsearch9 -t jaegertracing/spark-dependencies:elasticsearch9 .

在测试中，可以通过环境变量JAEGER_VERSION或系统属性jaeger.version指定Jaeger镜像的版本。默认情况下，测试使用最新镜像。

以下环境变量用于集成测试：

• SPARK_DEPENDENCIES_JOB_TAG：指定测试中使用的 Docker 镜像标签（例如 test-cassandra、test-es7、test-es8、test-es9）
• ELASTICSEARCH_VERSION：指定 Testcontainers 使用的 Elasticsearch 版本
• JAEGER_VERSION：（可选）指定测试中使用的 Jaeger 镜像版本。默认为 latest。

您也可以将其设置为系统属性：

./mvnw test -Djaeger.version=2.14.0

故障排除

Docker 权限问题

如果遇到 Docker 权限问题，请确保您的用户属于 docker 组：

sudo usermod -aG docker $USER

然后登出并重新登录。

Testcontainers 问题

如果 Testcontainers 启动失败，请确保：

1. Docker 正在运行且可访问
2. 已拉取 Ryuk 镜像：docker pull testcontainersofficial/ryuk:latest
3. 有足够的磁盘空间用于存储 Docker 镜像

构建失败

如果遇到构建失败：

1. 确保已安装 Java 21
2. 清理 Maven 缓存：./mvnw clean
3. 尝试使用 -U 标志强制更新依赖项：./mvnw -U clean install

端口冲突

如果测试因端口冲突而失败，请确保没有其他服务在 Testcontainers 使用的端口上运行（通常是临时端口，但有时是标准端口，如 Cassandra 的 9042 或 Elasticsearch 的 9200）。

CI/CD 流水线

项目使用统一的 CI/CD 流水线（.github/workflows/ci-cd.yml），该流水线实现了主机构建矩阵模式（Host-Build Matrix Pattern）：

1. 设置与依赖项下载 - 一次性下载所有 Maven 依赖项，并为后续作业预热缓存
2. 构建 JAR - 在 GitHub 运行器上构建特定于存储的 JAR（所有变体并行构建）
3. 端到端测试 - 使用带有预构建 JAR 的 Docker 容器测试每个变体
4. 发布 - 将多架构 Docker 镜像（linux/amd64、linux/arm64）发布到 GitHub Container Registry

流水线支持四个变体：

• cassandra - 适用于 Cassandra 存储
• elasticsearch7 - 适用于 Elasticsearch 7.12-7.16（ES 连接器 7.17.29）
• elasticsearch8 - 适用于 Elasticsearch 7.17+ 和 8.x（ES 连接器 8.13.4）
• elasticsearch9 - 适用于 Elasticsearch 9.x（ES 连接器 9.1.3）

这种方法消除了 Docker 构建中的 Maven 下载，并跨所有存储变体并行化构建过程。

许可证

Apache 2.0 许可证。