Persistent Zipkin server with MySQL/MariaDB storage

Introduction

In this tutorial I’ll show how to set up Zipkin on Ubuntu 22.04 (Jammy), using a local MariaDB server for persistance.

⚠️ Disclaimer: This setup is meant as a tech-demo and a minimal usable setup. It does not have the adequate security or reliability levels required for production environments. Use only on trusted, isolated networks!

Download the prerequisites

Zipkin itself is delivered as a Java JAR application, so you’ll need a Java Runtime along with the application for it to run. For the storage we’ll install a database engine (MariaDB) on the same machine, and to complete the setup we’ll also need the database schema initialisation script.

# Install MariaDB & a Java runtime locally using the package-manager
sudo apt-get install mariadb-server openjdk-18-jre

# Download the exec.JAR application.
# You can use the Maven repository to pick the latest release:
# https://search.maven.org/artifact/io.zipkin/zipkin-server/
wget https://search.maven.org/remotecontent?filepath=io/zipkin/zipkin-server/2.23.19/zipkin-server-2.23.19-exec.jar -O zipkin-server-2.23.19-exec.jar

# Download the schema configuration
wget https://raw.githubusercontent.com/openzipkin/zipkin/master/zipkin-storage/mysql-v1/src/main/resources/mysql.sql

Create the database, database user and initial schema

We need to get to the administrator console of the database, to set up the initial db.

# Start the SQL console
sudo mysql -uroot

And then in the SQL console:

-- create the database
CREATE DATABASE IF NOT EXISTS zipkin;

-- create the role
-- replace 'pass' with a stronger password
CREATE USER zipkin@localhost IDENTIFIED BY pass;
GRANT ALL PRIVILEGES ON zipkin.* TO zipkin@localhost;
SHOW GRANTS FOR zipkin@localhost;

The last command (SHOW GRANTS) should output something like

MariaDB [(none)]> SHOW GRANTS FOR zipkin@localhost;
+---------------------------------------------------------------------------+
| Grants for zipkin@localhost                                               |
+---------------------------------------------------------------------------+
| GRANT USAGE ON *.* TO `zipkin`@`localhost` IDENTIFIED BY PASSWORD '.....' |
| GRANT ALL PRIVILEGES ON `zipkin`.* TO `zipkin`@`localhost`                |
+---------------------------------------------------------------------------+
2 rows in set (0.001 sec)

And now, return to the regular shell, to configure the initial schema. You can also look at the official guide of the mysql backend.

sudo mysql -uroot -Dzipkin < mysql.sql

Start the Zipkin server

That’s it, you can now start the server. Don’t forget to replace the hardcoded password from the environment with the stronger password you chose previously. For more information about the starting parameters look at the official documentation

STORAGE_TYPE=mysql MYSQL_USER=zipkin MYSQL_PASS=pass java -jar zipkin-server-2.23.19-exec.jar

The server will be available on port 9411, open for HTTP and REST API requests.

Note that the database might be exposed to the network and that zipkin will accept any traces via REST API. Only use in trusted environments.