Announcing Astyanax

By Eran Landau 

Over the past year we have been investing heavily in Cassandra as our primary persistent storage solution. We currently run 55 separate clusters, ranging from 6 to 48 nodes. We've been active contributors to Cassandra and have developed additional tools and our own client library. Today we are open sourcing that client, Astyanax, as part of our ongoing open source initiative. Astyanax started as a re-factor of Hector, but our experience running with a large number of diverse clusters has enabled us to tune the client for various scenarios and focus on wide range of client use cases.

What is Astyanax?

Astyanax is a Java Cassandra client. It borrows many concepts from Hector but diverges in the connection pool implementation as well as the client API. One of the main design considerations was to provide a clean abstraction between the connection pool and Cassandra API so that each may be customized and improved separately. Astyanax provides a fluent style API which guides the caller to narrow the query from key to column as well as providing queries for more complex use cases that we have encountered. The operational benefits of Astyanax over Hector include lower latency, reduced latency variance, and better error handling.

Astyanax is broken up into three separate parts:

connection pool	The connection pool abstraction and several implementations including round robin, token aware and bag of connections.
cassandra-thrift API implementation	Cassandra Keyspace and Cluster level APIs implementing the thrift interface.
recipes and utilities	Utility classes built on top of the astyanax-cassandra-thrift API.

Astyanax API

Astyanax implements a fluent API which guides the caller to narrow or customize the query via a set of well defined interfaces. We've also included some recipes that will be executed efficiently and as close to the low level RPC layer as possible. The client also makes heavy use of generics and overloading to almost eliminate the need to specify serializers.

Some key features of the API include:

• Key and column types are defined in a ColumnFamily class which eliminates the need to specify serializers.
• Multiple column family key types in the same keyspace.
• Annotation based composite column names.
• Automatic pagination.
• Parallelized queries that are token aware.
• Configurable consistency level per operation.
• Configurable retry policy per operation.
• Pin operations to specific node.
• Async operations with a single timeout using Futures.
• Simple annotation based object mapping.
• Operation result returns host, latency, attempt count.
• Tracer interfaces to log custom events for operation failure and success.
• Optimized batch mutation.
• Completely hide the clock for the caller, but provide hooks to customize it.
• Simple CQL support.
• RangeBuilders to simplify constructing simple as well as composite column ranges.
• Composite builders to simplify creating composite column names.

Recipes

Recipes for some common use cases:

• CSV importer.
• JSON exporter to convert any query result to JSON with a wide range of customizations.
• Parallel reverse index search.
• Key unique constraint validation.

Connection pool

The Astyanax connection pool was designed to provide a complete abstraction from the client API layer. One of our main goals when preparing Astyanax to be open sourced was to properly decouple components of the connection pool so that others may easily plug in their customizations. For example, we have our own middle tier load balancer that keeps track of nodes in the cluster and have made it the source of seed nodes to the client.

Key features of the connection pool are:

HostSupplier/NodeAutoDiscovery	Background task that frequently refreshes the client host list. There is also an implementation that consolidates a describe ring against the local region's list of hosts to prevent cross-regional client traffic.
TokenAware	The token aware connection pool implementation keeps track of which hosts own which tokens and intelligently directs traffic to a specific range with fallback to round robin.
RoundRobin	This is a standard round robin implementation
Bag	We found that for our shared cluster we needed to limit the number of client connections. This connection pool opens a limited number of connections to random hosts in a ring.
ExecuteWithFailover	This abstraction lets the connection pool implementation capture a fail-over context efficiently
RetryPolicy	Retry on top of the normal fail-over in ExecuteWithFailover. Fail-over addresses problems such as connections not available on a host, a host going down in the middle of an operation or timeouts. Retry implements backoff and retrying the entire operation with an entirely new context.
BadHostDetector	Determine when a node has gone down, based on timeouts
LatencyScoreStrategy	Algorithm to determine a node's score based on latency. Two modes, unordered (round robin) ordered (best score gets priority)
ConnectionPoolMonitor	Monitors all events in the connection pool and can tie into proprietary monitoring mechanisms. We found that logging deep in the connection pool code tended to be very verbose so we funnel all events to a monitoring interface so that logging and alerting may be controlled externally.
Pluggable real-time configuration	The connection pool configuration is kept by a single object referenced throughout the code. For our internal implementation this configuration object is tied to volatile properties that may change at run time and are picked up by the connection pool immediately thereby allowing us to tweak client performance at runtime without having to restart.
RateLimiter	Limits the number of connections that can be opened within a given time window. We found this necessary for certain types of network outages that cause thundering herd of connection attempts overwhelming Cassandra.

A taste of Astyanax

Here's a brief code snippet to give you a taste of what the API looks like


Accessing Astyanax

• The Astyanax binaries are posted to Maven Central which makes accessing them very easy
• The source code for Astyanax is hosted at Github: https://github.com/Netflix/astyanax
• Extensive documentation is currently at https://github.com/Netflix/astyanax/wiki/Getting-Started