Dogtag

A Redis-powered Ruby client for generating unique IDs with Redis for use in distributed systems. Based heavily off of Icicle and Twitter Snowflake

Requirements

• Ruby
• Redis

Installation

Simply add gem 'dogtag' to your Gemfile and run bundle

Configuration

To configure the connection to your Redis server simply set a DOGTAG_REDIS_URL or REDIS_URL environment variable. Dogtag will first look for the DOGTAG_REDIS_URL, then REDIS_URL. If neither are found it will default to redis://127.0.01:6379.

To set the range of logical shard IDs this server should manage, run the command below replacing the number range with a range of numbers, of which none can be shared with another Redis server. If a logical shard ID is shared a separate Redis instance, you may get ID collisions.

bundle exec ruby -e 'require "dogtag"; Dogtag.logical_shard_id_range = 0..31'

Note: The available shard ID numbers are current 0 - 31.

Usage

data_type = 0
Dogtag.generate_id data_type

data_type = 42
count = 100
Dogtag.generate_ids data_type, count

id_number = Dogtag.generate_id 42
id = Dogtag::Id.new(id_number)
id.data_type #=> 42
id.sequence #=> 1
id.logical_shard_id #=> 12
id.custom_timestamp # time since custom epoch
id.timestamp.to_i #=> 28146773761 # Unix timestamp
id.timestamp.to_time # Ruby Time object
id.timestamp.epoch #=> 1483228800000

Note: The available data type ID numbers are current 0 - 255.

A list of existing IDs types and numbers can be found: https://github.com/zillyinc/zilly-backend/blob/master/config/initializers/tellus_dogtag.rb

Gotchas

• If you are going to store the ID in the database you'll need to make sure it can store 64 bit integers. In Rails this means using integer limit: 8 in your migrations.
• Be careful of using Dogtag IDs with JavaScript, since it doesn't handle 64 bit integers well. You'll probably want to work with them as strings.

Related Projects

• dogtag-web - Web API for dogtag

Testing

Simply spin up a Redis server and run bundle exec rspec.

TODO

• Support multiple Redis servers