Skip to content

Identity Generators

Snowflake Identity Generator

Info

This is only available in Agrona 1.11.0+

When building uncoordinated distributed systems, we sometimes require globally unique identity values. Snowflake - as originally implemented by Twitter - provides this capability, and Agrona includes an implementation of the algorithm.

Snowflake, as implemented in Agrona, has the following default properties:

  • each generated identity is a 64bit number
  • identities are roughly sortable
  • up to 4,096,000 unique identities per second can be generated. If the caller attempts to generate more than 4,096 items in a given millisecond, the library will busy spin until the clock ticks to the next millisecond.
  • if the system clock steps backwards, you can expect an IllegalStateException to be thrown
  • lock free and thread safe (it makes use of atomic compareAndSet internally)

To configure a basic Snowflake Identity Generator, you must provide a unique node Id. This should be unique within the space of nodes generating identities in your system - for example, if you have a system composed of 5 processes that are each generating values with the Snowflake Identity Generator, then each of these should receive a unique node Id — for example 1,2,3,4 and 5. The standard configuration of the Agrona Snowflake Identity Generator supports at most 1024 nodes. This is a simplification of the original Twitter Snowflake algorithm, which used 5 bits for a data center identity and 5 bits for a worker identity.

Using the Snowflake Identity Generator is simple:

final long nodeId = 1L;
final IdGenerator idGenerator = new SnowflakeIdGenerator(nodeId);

final long nextId = idGenerator.nextId();

Note that Snowflake is able to generate unique identities for a period of 69 years. By default, the Agrona library uses 1970 as the starting point, so identities will be extinguished in 2039. There is an overloaded constructor that lets you specify your own offset, so you could set this to 2021 and create unique identities until 2090. This same constructor allows for a custom EpochClock implementation to be provided, and for customization of the number of bits dedicated to sequences and the node identities. A sample using this constructor is on GitHub.