Zipkin 安装与运行教程
前言
技术资源
三种运行方式
Zipkin 支持三种运行方式,包括:
- 从源码运行
- Java 命令运行
- Docker 容器运行
Zipkin 控制台访问
当 Zipkin 的服务正常运行后,默认会监听 9411
端口,浏览器可以通过 http://127.0.0.1:9411/zipkin/
访问 Zipkin 的 Web 管理控制台。
Java 命令运行
最快的运行方式是从 这里 获取最新发布的 Zipkin 可执行 Jar 文件,然后直接使用 java -jar
命令运行。特别注意,最新版本的 Zipkin 至少需要依赖 Java 17+。
1 | # 下载最新版本的可执行 Jar 文件 |
Zipkin 正常运行后输出的日志信息如下,默认会监听 9411
端口。
浏览器通过 http://127.0.0.1:9411/zipkin/
就可以访问 Zipkin 的 Web 管理控制台。
Docker 运行
Docker 直接运行
1 | docker run -d --name zipkin --restart=always -p 9411:9411 -e TZ=Asia/Shanghai -e STORAGE_TYPE=mem openzipkin/zipkin:3.4.1 |
Docker Compose 运行
1 | version: '3.5' |
- 重要参数说明:
STORAGE_TYPE=mem
:使用内存作为存储(默认配置),服务重启后会丢失数据。
Zipkin 数据持久化
Zipkin 支持将追踪数据存储到 Cassandra、Elasticsearch、MySQL。值得一提的是,Zipkin 默认会将追踪数据存储到内存中,服务重启后会丢失数据。
MySQL 持久化
官方文档
Zipkin 支持将数据持久化到 MySQL,详细的说明可以参考 官方文档。
特别注意
- 在 Zipkin 连接 MySQL 之前,必须手动初始化 MySQL 数据库,比如创建数据库、表结构、用户等。
- 建议使用 MySQL
5.7.x
版本,而不是使用 MySQL8.x
版本,否则可能会因为 Zipkin 不支持高版本的 MySQL,导致 Zipkin 无法正常运行,具体表现为 Zipkin 无法往 MysQL 查询或插入追踪数据。
数据库初始化
- 创建数据库,用于 Zipkin 存储追踪数据
1 | CREATE DATABASE zipkin DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci; |
- 切换数据库
1 | use zipkin; |
- 创建表结构,最新的 DDL 语句可以从 这里 获得
1 | CREATE TABLE IF NOT EXISTS zipkin_spans ( |
- 创建用户并授权,用于 Zipkin 连接 MySQL 数据库
1 | -- 创建用户 |
Java 命令运行
当使用 Java 命令运行 Zipkin 时,可以在启动的时候指定所需的环境变量,比如 MySQL 的地址、端口、用户名、密码等信息。
1 | STORAGE_TYPE=mysql MYSQL_HOST=127.0.0.1 MYSQL_TCP_PORT=3306 MYSQL_DB=zipkin MYSQL_USER=zipkin MYSQL_PASS=zipkin java -jar zipkin.jar |
- 重要参数说明:
STORAGE_TYPE=mysql
:使用 MySQL 作为存储。
MySQL 版本说明
通过 Java 命令运行最新版的 Zipkin (如 3.4.1
)时,亲测可以使用 MySQL 5.7.44
或者 MySQL 8.4.2
,不会出现无法连接 MySQL 的情况。
Docker 直接运行
当使用 Docker 直接运行 Zipkin 时,可以在启动容器的时候指定所需的环境变量,比如 MySQL 的地址、端口、用户名、密码等信息。
1 | docker run \ |
- 重要参数说明:
STORAGE_TYPE=mysql
:使用 MySQL 作为存储。MYSQL_HOST=192.168.5.168
:MySQL 的 IP 地址,这里的 MySQL 可以不是运行在 Docker 容器里的(即可以单独安装)。
特别注意
通过 Docker 直接运行最新版的 Zipkin(如 3.4.1
)时,必须使用 MySQL 5.7.44
版本,笔者尝试使用 MySQL 8.4.2
版本,发现 Zipkin 不能正常运行,也就是无法连接 MySQL,具体表现为 Zipkin 无法往 MysQL 查询或插入追踪数据。
Docker Compose 运行
若需要将追踪数据存储到 MySQL,可以修改 docker-compose.yml
中的 STORAGE_TYPE
为 mysql
,并配置相应的存储服务信息。
1 | version: '3.5' |
- 重要参数说明:
STORAGE_TYPE: mysql
:使用 MySQL 作为存储。MYSQL_HOST: mysql
:这里的mysql
是在 Docker Compose 中定义的 MySQL 服务的名称,用作其他服务(如 Zipkin)访问 MySQL 的主机名,Docker Compose 会自动将这个名称解析为 MySQL 容器的 IP 地址。
特别注意
- 当通过 Docker Compose 启动 Zipkin 和 MySQL 容器后,可以发现 Zipkin 并不能正常提供服务,比如在 Web 控制台上面无法查询到数据。
- 这通常是因为在 MySQL 数据库中,并没有 Zipkin 所需要的表结构和用户,因此需要手动创建数据库、表结构和用户,详细的操作步骤请看 这里。
- 通过 Docker Compose 运行最新版的 Zipkin(如
3.4.1
)时,必须使用 MySQL5.7.44
版本,笔者尝试使用 MySQL8.4.2
版本,发现 Zipkin 不能正常运行,也就是无法连接 MySQL,具体表现为 Zipkin 无法往 MysQL 查询或插入追踪数据。
Elasticsearch 持久化
官方文档
Zipkin 支持将数据持久化到 Elasticsearch,详细的说明可以参考 官方文档。
特别注意
- 在 Zipkin 连接 Elasticsearch 之前,不需要手动初始化 Elasticsearch,比如创建索引。
- Zipkin 默认使用了 Elasticsearch
5+
的功能,但针对 Elasticsearch7
~8.x
版本和 OpenSearch2.x
也进行了测试,笔者亲测 Zipkin 可以正常使用 Elasticsearch7.17.4
。
Java 命令运行
当使用 Java 命令运行 Zipkin 时,可以在启动的时候指定所需的环境变量,比如 Elasticsearch 的连接地址。
1 | STORAGE_TYPE=elasticsearch ES_HOSTS=http://127.0.0.1:9200 java -jar zipkin.jar |
- 重要参数说明:
STORAGE_TYPE=elasticsearch
:使用 Elasticsearch 作为存储。ES_HOSTS=http://127.0.0.1:9200
:指定 Elasticsearch 的连接地址。
Docker 直接运行
当使用 Docker 直接运行 Zipkin 时,可以在启动容器的时候指定所需的环境变量,比如 Elasticsearch 的连接地址。
1 | docker run \ |
- 重要参数说明:
STORAGE_TYPE=elasticsearch
:使用 Elasticsearch 作为存储。ES_HOSTS=http://192.168.5.168:9200
:指定 Elasticsearch 的连接地址,这里的 Elasticsearch 可以不是运行在 Docker 容器里的(即可以单独安装)。
Docker Compose 运行
若需要将追踪数据存储到 Elasticsearch,可以修改 docker-compose.yml
中的 STORAGE_TYPE
为 elasticsearch
,并配置相应的存储服务信息。
1 | version: '3.5' |
- 重要参数说明:
STORAGE_TYPE=elasticsearch
:使用 Elasticsearch 作为存储。ES_HOSTS: http://elasticsearch:9200
:这里的elasticsearch
是在 Docker Compose 中定义的 ElasticSearch 服务的名称,用作其他服务(如 Zipkin)访问 ElasticSearch 的主机名,Docker Compose 会自动将这个名称解析为 ElasticSearch 容器的 IP 地址。若连接的是 ElasticSearch 集群,可以使用逗号分割多个 URL 地址。
Zipkin 数据采集
Zipkin 支持多种数据采集方式,包括从 Kafka、RabbitMQ、ActiveMQ 采集追踪数据,详细的 Docker 使用说明请参考 官方的 Docker 使用示例。
常见的使用错误
MySQL 持久化失败
错误描述
:当 Zipkin 使用 MySQL 作为存储时,Zipkin 容器无法正常启动,通过docker logs zipkin
命令得到容器启动时的错误日志信息如下:
1 | Version mismatch : Database version is older than what dialect MYSQL supports: 5.7.44. |
错误分析
:从表面看像是当前使用的 Zipkin 版本并不支持低版本的 MySQL(比如5.7.44
)。但是,笔者尝试将 MySQL 镜像的版本升级到8.4.2
,发现 Zipkin 不能正常运行,也就是无法连接 MySQL,具体表现为 Zipkin 无法往 MysQL 查询或插入追踪数据。解决方法
:重启 Zipkin 容器即可,使用的命令如下:
1 | # 重启容器 |