Chronos is an event-capturing framework for greenfield applications and is built with NodeJS, Apache Kafka, TimescaleDB, and PipelineDB. This repository contians the data pipeline itself that is set up on a host server to store your event data for further analysis. Data can then be visualized using Grafana. You can read about our story of creating Chronos here.
Chronos comes with a CLI to make installing and running the pipeline easier for developers. You must have NodeJS as well as npm installed in order to use the CLI.
If you wish to add Chronos to your path, from the root directory of the repository run ./setup.sh. This will add the bin directory which contains the chronos executable to your path via your .bashrc file (which also means that chronos assumes that .bashrc will be sourced). If you don't want to add chronos to your path, from the root directory of the repository you can run all the commands by first entering bin/chronos.
The CLI supports the following commands:
| Command | Description |
|---|---|
start [service] |
Starts either Chronos or a specified service |
stop [service] |
Stops either Chronos or a specified service |
log (service) |
Prints the logs of a service to the terminal |
status |
Prints the status of the services to the terminal |
install-kafka |
Installs the events topic used by the Kafka brokers |
install-pipeline |
Sets up the chronos_pl database used by PipelineDB |
Chronos is currently deployed only through Docker, which thus must be installed on the host machine. In addition, the host machine must also have Docker Compose installed in order to run the docker-compose.yml file which orchestrates the setup.
To begin installing the Chronos pipeline, first clone the master branch of this repository. Then use docker-compose pull to pull the required images. You may then either finish the installation by using the Chronos CLI or with Docker.
To finish the installation with the CLI, just run chronos install-kafka and chronos install-pipeline. Once that's done, Chronos should be installed.
To finish the installation with Docker, you must first boot up Zookeeper and all 3 Kafka brokers in order to set up the events topic. This is most easily done by running the following:
docker-compose up -d zookeeper
docker-compose up -d kafka-1
docker-compose up -d kafka-2
docker-compose up -d kafka-3
Then enter:
docker-exec -it chronos-pipeline_kafka-1_1 kafka-topics --zookeeper zookeeper:2181 --create --topic events --partitions 6 --replication-factor 3 --if-not-exists
You can then use docker-compose stop to stop the currently running containers. Next, you must boot up the PipelineDB container in order to set up the chronos_pl database. First, run docker-compose up -d pipeline to start the PipelineDB container. Then, from the root folder of the repository, run the following:
docker-exec -it chronos-pipeline_pipeline_1 psql -U postgres -d chronos_pl < db/setup_pipelinedb.sql
Once this is done, you may stop the container by running docker-compose stop. At this point Chronos should be installed.
Note: Normally SQL files in the /docker-entrypoint-initdb.d directory are automatically dumped when a container is first created, but there is currently a bug that prevents PipelineDB from properly setting up the relations specified in a SQL dump.
Chronos authenticates by using middleware that whitelists specified origins and verifies the authentication key sent by the tracker. To generate a key, in the server directory run npm run generate_new_access_key. To whitelist an origin, run npm run add_new_allowed_origin foo where foo is the origin you wish to allow. To remove an origin, run npm run remove_allowed_origin foo. You may also manually alter the config.json instead of using the scripts.
If using the CLI, you can use chronos start to boot up Chronos. If using Docker, first run docker-compose up -d zookeeper. Let this run for 5-10 seconds and then run docker-compose up to start up the rest of the system. You must expost port 3000 for the Express server, and port 4000 for Grafana.
The default account and password for Grana is admin. Grafana will prompt you to enter a new password for the admin account (which is highly recommended). To connect Grafana to TimescaleDB and PipelineDB, go to Configuration --> Data Sources and enter the following information in each of the specified fields when creating a connection to a new PostgreSQL database:
| Field | TimescaleDB | PipelineDB |
|---|---|---|
| Host | timescale:5432 |
pipeline:5432 |
| Database | chronos_ts |
chronos_pl |
| User | postgres |
postgres |
| Password | postgres_password |
postgres_password |
| SSL mode | disable |
disable |
| Version | 10 |
10 |
| TimescaleDB | ✅ | ❌ |
Once you click "Save and Test" you should get a green confirmation pop-up if everything is properly installed.
Nick Calibey Software Engineer Tulsa, OK
Sasha Prodan Software Engineer San Francisco, CA