Refactor BalancedMetricResolver to allow HDFS and FILE backing, add callbacks for major events, begin working on tests

Refactor BalancedMetricResolver, allow FILE or HDFS persister, add callbacks for events, begin working on testing

Fixes

.gitignore

@@ -4,3 +4,7 @@
 target/
 .idea/
 *.iml
+logs/
+server/pki/
+client/src/main/python/setup.py
+

CONTRIBUTORS

@@ -3,3 +3,4 @@ Eric Newton ([email protected])
 Jim Klucar ([email protected])
 Charlie Williams ([email protected])
 Drew Farris ([email protected])
+Brian Loss ([email protected])

README.md

@@ -1,180 +1,8 @@
-# Timely
----
+![Timely](timely-readme-logo.png)
 
-Timely is a time series database application that provides secure access to time series data. Timely is written in Java and designed to work with [Apache Accumulo] (http://accumulo.apache.org/) and [Grafana] (http://www.grafana.org).
+[![Apache License][li]][ll]
 
-# Design
----
-
-Being big users of Apache Accumulo, when we required a time series database application we looked to use software that was compatible with it. Specifically, we started with [OpenTSDB] (http://www.opentsdb.net) and Eric Newton's [Accumulo-OpenTSDB] (https://github.com/ericnewton/accumulo-opentsdb) project to bridge them together and Grafana for visualization. We ultimately ran into some issues that we could not work around. After much discussion we decided to replace OpenTSDB with something more native to Apache Accumulo. The implementation of Timely started with the following constraints and assumptions:
-
-1. We need to show progress quickly.
-2. We started with Grafana, so we didn't need our own user interface.
-3. We already had experience with OpenTSDB, so we started with its API.
-4. Space is cheap, ingest and query speed are more important.
-5. Metrics will be kept short term.
-6. The number of tags used for each metric will be small \( < 10 \).
-7. We can create a better API and Grafana plugin at a later time.
-
-## Building
-
-Timely uses Maven for compiling source, running tests, and packaging distributions. Below is a set of useful Maven lifecyles that we use:
- 
-Command | Description
---------|------------
-mvn compile | Compiles and formats the source
-mvn test | Runs unit tests
-mvn package | Runs findbugs and creates a distribution
-mvn verify | Runs integration tests
-mvn verify site | Creates the site
- 
-The [CollectD] (http://collectd.org/) plugins require that CollectD is installed locally as the `/usr/share/collectd/java/collectd-api.jar` file is a dependency.
-
-## Deployment
-
-The Timely server requires a Java 8 runtime. Timely utilizes iterators for Apache Accumulo, so your Accumulo instance will need to be run with Java 8 also.
-
-Create a distribution and untar it somewhere. Modify the `conf/timely.properties` file appropriately. Then, copy the `timely-server` and `commons-lang3` jar files to your Accumulo tservers. Next, launch Timely by running the `bin/timely-server.sh` script.
-
-If you just want to kick the tires without having to install and setup Apache Hadoop and Apache Accumulo, then you can start Timely with the `bin/timely-standalone.sh` script. This will start an Accumulo MiniCluster in the background, but be aware that the standalone instance will not save your metric data across restarts.
-
-## API
-
-The current Timely API is compatible with a subset of the OpenTSDB API. We currently support the OpenTSDB TCP put API and we have partially implemented the following HTTP operations that the Grafana OpenTSDB datasource uses:
-
-    * /api/aggregators
-    * /api/query
-    * /api/search/lookup
-    * /api/suggest
-
-We also provide the following additional endpoints:
-
-    * /login
-
-This endpoint should be used for non-anonymous access. It supports a POST request with username and password, or a GET request with SSL mutual authentication.
-
-    * /api/metrics
-
-This endpoint reports the metric names and tags that have been pushed to Timely. Eviction of this information is configurable, so it may reflect metrics that have been reported in the past but are no longer being actively reported. This could be useful in creating graphs in Grafana (so you won't have to go digging in the `meta` table in Accumulo).
-
-## Storage Format
-
-Metrics sent to Timely are stored in two Accumulo tables, `meta` and `metrics`. The `meta` table stores information about the metric names and tags. It's format is:
-
-Row | ColumnFamily | ColumnQualifier | Value
-----|:-------------|:----------------|:-----
-m:metric | | |
-t:metric | tagKey | |
-v:metric | tagKey | tagValue |
-
-The `metrics` table stores the datapoints using the following format:
-
-Row | ColumnFamily | ColumnQualifier | Value
-----|:-------------|:----------------|:-----
-metric\timestamp | tagKey=tagValue | tagKey=tagValue,tagKey=tagValue,... | metricValue
-
-As an example, if you sent the following metric to the put api
-
-```
-put sys.cpu.user 1447879348291 2.0 rack=r001 host=r001n01 instance=0
-```
-
-it would get stored in the following manner in the `meta` table:
-
-Row | ColumnFamily | ColumnQualifier | Value
-----|:-------------|:----------------|:-----
-m:sys.cpu.user | | |
-t:sys.cpu.user | host | | 
-t:sys.cpu.user | instance | | 
-t:sys.cpu.user | rack | | 
-v:sys.cpu.user | host | r001n01 | 
-v:sys.cpu.user | instance | 0 | 
-v:sys.cpu.user | rack | r001 | 
-
-and in the following manner in the `metrics` table
-
-Row | ColumnFamily | ColumnQualifier | Value
-----|:-------------|:----------------|:-----
-sys.cpu.user\1447879348291 | host=r001n01 | instance=0,rack=r001    | 2.0
-sys.cpu.user\1447879348291 | instance=0   | host=r001n01,rack=r001  | 2.0
-sys.cpu.user\1447879348291 | rack=r001    | host=r001n01,instance=0 | 2.0
-
-## Configuration
-
-The `NUM_SERVER_THREADS` variable in the `timely-server.sh` script controls how many threads are used in the Netty event group for TCP and HTTP operations. The TCP and HTTP groups use a different event group, so if you set the value to 8, then you will have 8 threads for TCP operations and 8 threads for HTTP operations. The properties file in the `conf` directory supports the following properties:
-
-Property | Description | Default Value
-:--------|:------------|:-------------
-timely.ip | The ip address where the Timely server is running |
-timely.port.put | The port that will be used for processing put requests |
-timely.port.query | The port that will be used for processing query requests |
-timely.instance\_name | The name of your Accumulo instance |
-timely.zookeepers |  The list of Zookeepers for your Accumulo instance |
-timely.username | The username that Timely will use to connect to Accumulo |
-timely.password | The password of the Accumulo user |
-timely.table | The name of the metrics table | timely.metrics
-timely.meta | The name of the meta table | timely.meta
-timely.write.latency | The Accumulo BatchWriter latency | 5s
-timely.write.threads | The Accumulo BatchWriter number of threads | [default](https://github.com/apache/accumulo/blob/master/core/src/main/java/org/apache/accumulo/core/client/BatchWriterConfig.java#L49)
-timely.write.buffer.size | The Accumulo BatchWriter buffer size | [default](https://github.com/apache/accumulo/blob/master/core/src/main/java/org/apache/accumulo/core/client/BatchWriterConfig.java#L40)
-timely.metric.age.off.days | The number of days to keep metrics | 7
-timely.cors.allow.any.origin | Allow any origin in cross origin requests (true/false) | false
-timely.cors.allow.null.origin | Allow null origins in cross origin requests (true/false) | false
-timely.cors.allowed.origins | List of allowed origins in cross origin requests (can be null or comma separated list)
-timely.cors.allowed.methods | List of allowed methods for cross origin requests | <ul><li>DELETE</li><li>GET</li><li>HEAD</li><li>OPTIONS</li><li>PUT</li><li>POST</li></ul>
-timely.cors.allowed.headers | Comma separated list of allowed HTTP headers for cross origin requests | content-type
-timely.cors.allow.credentials | Allow credentials to be passed in cross origin requests (true/false) | true
-timely.scanner.threads | Number of BatchScanner threads to be used in a query | 4
-timely.metrics.report.tags.ignored | Comma separated list of tags which will not be shown in the /api/metrics response |
-timely.meta.cache.expiration.minutes | Number of minutes after which unaccessed meta information will be purged from the meta cache | 60
-timely.meta.cache.initial.capacity | Initial capacity of the meta cache | 2000
-timely.meta.cache.max.capacity | Maximum capacity of the meta cache | 10000
-timely.ssl.certificate.file | Public certificate to use for the Timely server (x509 pem format) |
-timely.ssl.key.file | Private key to use for the Timely server (in pkcs8 format) |
-timely.ssl.key.pass | Password to the private key |
-timely.ssl.use.generated.keypair | Use a generated certificate/key pair - useful for testing | false
-timely.ssl.trust.store.file | Certificate trust store (a concatenated list of trusted CA x509 pem certificates) |
-timely.ssl.use.openssl | Use OpenSSL (vs JDK SSL) | true
-timely.ssl.use.ciphers | List of allowed SSL ciphers | see Configuration.java
-timely.session.max.age | Setting for max age of session cookie (in seconds) | 86400
-timely.http.address | Address for the Timely server, used for the session cookie domain |
-grafana.http.address | Address for the Grafana server |
-timely.allow.anonymous.access | Allow anonymous access | false
-timely.visibility.cache.expiration.minutes | Column Visibility Cache Expiration (minutes) | 60
-timely.visibility.cache.initial.capacity | Column Visibility Cache Initial Capacity | 2000
-timely.visibility.cache.max.capacity | Column Visibility Cache Max Capacity | 10000
-
-## Security
-
-Timely allows users to optionally label their data using Accumulo column visibility expressions. To enable this feature, users should put the expressions in a tag named `viz`. Timely will [flatten] (http://accumulo.apache.org/1.7/apidocs/org/apache/accumulo/core/security/ColumnVisibility.html#flatten%28%29) this expression and store it in the column visibility of the data point in the metrics table. Column visibilities are *not* stored in the meta table, so anyone can see metric names, tag names, and tag values.
-
-Timely provides HTTPS access to the query endpoints. It is possible to allow anonymous access to these endpoints which will allow anyone to see unlabeled data. Timely uses Spring Security to configure user authentication and user role information. Users must call the `/login` endpoint for authentication and Timely will respond by setting a HTTP cookie with a session id. The response to a successful login will be a temporary redirect (HTTP 307) to the configured address for the Grafana server. Grafana itself must be configured to use https for this to work properly. For more information see the [Quick Start] (quick-start/QUICK_START.md) documentation.
-
-## Tuning
-
-1. Each thread in the Timely server that is used for processing TCP put operations has its own BatchWriter. Each BatchWriter honors the `timely.write.latency` and `timely.write.threads` configuration property, but the buffer size for each BatchWriter is `timely.write.buffer.size` divided by the number of threads. For example, if you have 8 threads processing put operations and the following settings, then you will have 8 BatchWriters each using 2 threads with a 30s latency and a maximum buffer size of 128M:
-
-   ```
-   timely.write.latency=30s
-   timely.write.threads=2
-   timely.write.buffer.size=1G
-   ``` 
-
-2. The `timely.scanner.threads` property is used for BatchScanners on a per query basis. If you set this to 32 and have 8 threads processing HTTP operations, then you might have 256 threads concurrently querying your tablet servers. Be sure to set your ulimits appropriately.
-
-3. The Timely server contains an object called the meta cache, which is a cache of the keys that would be inserted into the meta table if they did not already exist. This cache is used to reduce the insert load of duplicate keys into the meta table and to serve up data to the `/api/metrics` endpoint. The meta cache is an object that supports eviction based on last access time and can be tuned with the `timely.meta.cache.*`  properties.
-
-
-## NOTES
-
-1. Not shown in the examples is the encoding of the row and value. You can apply the Timely formatter to your metrics table using the Accumulo shell command:
-   ```
-   config -t timely.metrics -s table.formatter=timely.util.TimelyMetricsFormatter
-   ```
-
-2. You can create split points for your metrics table based on the 'm' column family in the meta table.
-
-3. You can lower the `table.scan.max.memory` property on your metrics table in an attempt to get data back faster from the tablet servers.
-
-4. If you don't mind losing some metric data in the event of an Accumulo tablet server death, you can set the `table.walog.enabled` property to false and the `table.durability` property to none on your metrics table. This should speed up ingest a little.
+Timely is a time series database application that provides secure access to time series data. Timely is written in Java and designed to work with [Apache Accumulo](https://accumulo.apache.org/) and [Grafana](https://www.grafana.com). Documentation is located [here](https://nationalsecurityagency.github.io/timely/).
 
+[li]: https://img.shields.io/badge/license-ASL-blue.svg
+[ll]: https://www.apache.org/licenses/LICENSE-2.0

analytics/.gitignore

@@ -0,0 +1,2 @@
+/bin/
+/target

analytics/conf/summarization.properties

@@ -0,0 +1,20 @@
+timelyHostname=
+timelyTcpPort=
+timelyHttpsPort=
+timelyWssPort=
+doLogin=
+#timelyUsername=
+#timelyPassword=
+keyStoreFile=
+keyStoreType=
+keyStorePass=
+trustStoreFile=
+trustStoreType=
+trustStorePass=
+hostVerificationEnabled=false
+bufferSize=10485760
+metrics=
+startTime=0
+endTime=0
+interval=1
+intervalUnits=HOURS

analytics/pom.xml

@@ -0,0 +1,257 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>timely</groupId>
+    <artifactId>timely</artifactId>
+    <version>1.2.8-SNAPSHOT</version>
+  </parent>
+  <artifactId>timely-analytics</artifactId>
+  <!--
+
+  Execute "mvn clean package -Pbuild-jar"
+  to build a jar file out of this project!
+
+  How to use the Flink Quickstart pom:
+
+  a) Adding new dependencies:
+  You can add dependencies to the list below.
+  Please check if the maven-shade-plugin below is filtering out your dependency
+  and remove the exclude from there.
+
+  b) Build a jar for running on the cluster:
+  There are two options for creating a jar from this project
+
+  b.1) "mvn clean package" -> this will create a fat jar which contains all
+  dependencies necessary for running the jar created by this pom in a cluster.
+  The "maven-shade-plugin" excludes everything that is provided on a running Flink cluster.
+
+  b.2) "mvn clean package -Pbuild-jar" -> This will also create a fat-jar, but with much
+  nicer dependency exclusion handling. This approach is preferred and leads to
+  much cleaner jar files.
+  -->
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.flink</groupId>
+      <artifactId>flink-clients_2.11</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.flink</groupId>
+      <artifactId>flink-java</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.flink</groupId>
+      <artifactId>flink-streaming-java_2.11</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>timely</groupId>
+      <artifactId>timely-client</artifactId>
+      <exclusions>
+        <exclusion>
+          <groupId>org.apache.logging.log4j</groupId>
+          <artifactId>*</artifactId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>timely</groupId>
+      <artifactId>timely-common</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <configuration>
+            <compilerId>jdt</compilerId>
+          </configuration>
+          <dependencies>
+            <dependency>
+              <groupId>org.eclipse.tycho</groupId>
+              <artifactId>tycho-compiler-jdt</artifactId>
+              <version>1.4.0</version>
+            </dependency>
+          </dependencies>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+    <plugins>
+      <plugin>
+        <groupId>org.jacoco</groupId>
+        <artifactId>jacoco-maven-plugin</artifactId>
+      </plugin>
+      <!-- We use the maven-shade plugin to create a fat jar that contains all dependencies
+      except flink and it's transitive dependencies. The resulting fat-jar can be executed
+      on a cluster. Change the value of Program-Class if your program entry point changes. -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-shade-plugin</artifactId>
+        <executions>
+          <!-- Run shade goal on package phase -->
+          <execution>
+            <goals>
+              <goal>shade</goal>
+            </goals>
+            <phase>package</phase>
+            <configuration>
+              <artifactSet>
+                <excludes>
+                  <!-- This list contains all dependencies of flink-dist
+                  Everything else will be packaged into the fat-jar
+                  -->
+                  <exclude>org.apache.flink:flink-annotations</exclude>
+                  <exclude>org.apache.flink:flink-shaded-hadoop1_2.11</exclude>
+                  <exclude>org.apache.flink:flink-shaded-hadoop2</exclude>
+                  <exclude>org.apache.flink:flink-shaded-curator-recipes</exclude>
+                  <exclude>org.apache.flink:flink-core</exclude>
+                  <exclude>org.apache.flink:flink-java</exclude>
+                  <exclude>org.apache.flink:flink-scala_2.11</exclude>
+                  <exclude>org.apache.flink:flink-runtime_2.11</exclude>
+                  <exclude>org.apache.flink:flink-optimizer_2.11</exclude>
+                  <exclude>org.apache.flink:flink-clients_2.11</exclude>
+                  <exclude>org.apache.flink:flink-avro_2.11</exclude>
+                  <exclude>org.apache.flink:flink-examples-batch_2.11</exclude>
+                  <exclude>org.apache.flink:flink-examples-streaming_2.11</exclude>
+                  <exclude>org.apache.flink:flink-streaming-java_2.11</exclude>
+                  <!-- Also exclude very big transitive dependencies of Flink
+                  WARNING: You have to remove these excludes if your code relies on other
+                  versions of these dependencies.
+                  -->
+                  <exclude>org.scala-lang:scala-library</exclude>
+                  <exclude>org.scala-lang:scala-compiler</exclude>
+                  <exclude>org.scala-lang:scala-reflect</exclude>
+                  <exclude>com.typesafe.akka:akka-actor_*</exclude>
+                  <exclude>com.typesafe.akka:akka-remote_*</exclude>
+                  <exclude>com.typesafe.akka:akka-slf4j_*</exclude>
+                  <exclude>io.netty:netty-all</exclude>
+                  <exclude>io.netty:netty</exclude>
+                  <exclude>commons-fileupload:commons-fileupload</exclude>
+                  <exclude>org.apache.avro:avro</exclude>
+                  <exclude>commons-collections:commons-collections</exclude>
+                  <exclude>org.codehaus.jackson:jackson-core-asl</exclude>
+                  <exclude>org.codehaus.jackson:jackson-mapper-asl</exclude>
+                  <exclude>com.thoughtworks.paranamer:paranamer</exclude>
+                  <exclude>org.xerial.snappy:snappy-java</exclude>
+                  <exclude>org.apache.commons:commons-compress</exclude>
+                  <exclude>org.tukaani:xz</exclude>
+                  <exclude>com.esotericsoftware.kryo:kryo</exclude>
+                  <exclude>com.esotericsoftware.minlog:minlog</exclude>
+                  <exclude>org.objenesis:objenesis</exclude>
+                  <exclude>com.twitter:chill_*</exclude>
+                  <exclude>com.twitter:chill-java</exclude>
+                  <exclude>commons-lang:commons-lang</exclude>
+                  <exclude>junit:junit</exclude>
+                  <exclude>org.apache.commons:commons-lang3</exclude>
+                  <exclude>org.slf4j:slf4j-api</exclude>
+                  <exclude>org.slf4j:slf4j-log4j12</exclude>
+                  <exclude>log4j:log4j</exclude>
+                  <exclude>org.apache.commons:commons-math</exclude>
+                  <exclude>org.apache.sling:org.apache.sling.commons.json</exclude>
+                  <exclude>commons-logging:commons-logging</exclude>
+                  <exclude>commons-codec:commons-codec</exclude>
+                  <exclude>com.fasterxml.jackson.core:jackson-core</exclude>
+                  <exclude>com.fasterxml.jackson.core:jackson-databind</exclude>
+                  <exclude>com.fasterxml.jackson.core:jackson-annotations</exclude>
+                  <exclude>stax:stax-api</exclude>
+                  <exclude>com.typesafe:config</exclude>
+                  <exclude>org.uncommons.maths:uncommons-maths</exclude>
+                  <exclude>com.github.scopt:scopt_*</exclude>
+                  <exclude>commons-io:commons-io</exclude>
+                  <exclude>commons-cli:commons-cli</exclude>
+                </excludes>
+              </artifactSet>
+              <filters>
+                <filter>
+                  <artifact>org.apache.flink:*</artifact>
+                  <excludes>
+                    <!-- exclude shaded google but include shaded curator -->
+                    <exclude>org/apache/flink/shaded/com/**</exclude>
+                    <exclude>web-docs/**</exclude>
+                  </excludes>
+                </filter>
+                <filter>
+                  <!-- Do not copy the signatures in the META-INF folder.
+                  Otherwise, this might cause SecurityExceptions when using the JAR.
+                  -->
+                  <artifact>*:*</artifact>
+                  <excludes>
+                    <exclude>META-INF/*.SF</exclude>
+                    <exclude>META-INF/*.DSA</exclude>
+                    <exclude>META-INF/*.RSA</exclude>
+                  </excludes>
+                </filter>
+              </filters>
+              <!-- If you want to use ./bin/flink run <quickstart jar> uncomment the following lines.
+                This will add a Main-Class entry to the manifest file -->
+              <!--
+                <transformers>
+                  <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                    <mainClass>jar.StreamingJob</mainClass>
+                  </transformer>
+                </transformers>
+                -->
+              <createDependencyReducedPom>false</createDependencyReducedPom>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>buildnumber-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+  <profiles>
+    <profile>
+      <!-- Profile for packaging correct JAR files -->
+      <id>build-jar</id>
+      <dependencies>
+        <dependency>
+          <groupId>org.apache.flink</groupId>
+          <artifactId>flink-clients_2.11</artifactId>
+          <scope>provided</scope>
+        </dependency>
+        <dependency>
+          <groupId>org.apache.flink</groupId>
+          <artifactId>flink-java</artifactId>
+          <scope>provided</scope>
+        </dependency>
+        <dependency>
+          <groupId>org.apache.flink</groupId>
+          <artifactId>flink-streaming-java_2.11</artifactId>
+          <scope>provided</scope>
+        </dependency>
+      </dependencies>
+      <build>
+        <plugins>
+          <!-- disable the exclusion rules -->
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-shade-plugin</artifactId>
+            <executions>
+              <execution>
+                <goals>
+                  <goal>shade</goal>
+                </goals>
+                <phase>package</phase>
+                <configuration>
+                  <artifactSet>
+                    <excludes combine.self="override" />
+                  </artifactSet>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
+</project>

analytics/src/main/java/timely/analytics/flink/MetricHistogram.java

@@ -0,0 +1,168 @@
+package timely.analytics.flink;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
+
+import org.apache.flink.streaming.util.serialization.SerializationSchema;
+import timely.model.Tag;
+
+public class MetricHistogram implements Serializable, SerializationSchema<MetricHistogram> {
+
+    private static final long serialVersionUID = 1L;
+    private static final String SPACE = " ";
+    private static final String AVG = " sample=avg\n";
+    private static final String COUNT = " sample=count\n";
+    private static final String MAX = " sample=max\n";
+    private static final String MIN = " sample=min\n";
+    private static final String SUM = " sample=sum\n";
+    private static final String p50 = " sample=50p\n";
+    private static final String p75 = " sample=75p\n";
+    private static final String p90 = " sample=90p\n";
+    private static final String p99 = " sample=99p\n";
+
+    private String metric = null;
+    private List<Tag> tags = null;
+    private long timestamp = 0L;
+    private boolean initialized = false;
+    private List<Double> values = new ArrayList<>();
+
+    public void initialize(String metric, List<Tag> tags) {
+        this.metric = metric;
+        this.tags = tags;
+        initialized = true;
+    }
+
+    public boolean isInitialized() {
+        return initialized;
+    }
+
+    public String getMetric() {
+        return metric;
+    }
+
+    public List<Tag> getTags() {
+        return tags;
+    }
+
+    public long getTimestamp() {
+        return timestamp;
+    }
+
+    public void update(Double d, long timestamp) {
+        values.add(d);
+        this.timestamp = timestamp;
+    }
+
+    public void done() {
+        Collections.sort(values);
+    }
+
+    public Double avg() {
+        if (values.size() == 0) {
+            return 0.0D;
+        }
+        return sum() / count();
+    }
+
+    public Double min() {
+        if (values.size() == 0) {
+            return 0.0D;
+        }
+        return values.get(0);
+    }
+
+    public Double max() {
+        if (values.size() == 0) {
+            return 0.0D;
+        }
+        return values.get(values.size() - 1);
+    }
+
+    public Double getPercentile(int p) {
+        if (values.size() == 0) {
+            return 0.0D;
+        }
+        int position = Math.round((p * 1.0f / 100) * values.size());
+        position = (0 == position) ? 0 : position - 1;
+        return values.get(position);
+    }
+
+    public Double count() {
+        return values.size() * 1.0D;
+    }
+
+    public Double sum() {
+        double sum = 0.0D;
+        for (Double d : values) {
+            sum += d;
+        }
+        return sum;
+    }
+
+    @Override
+    public String toString() {
+        done();
+        StringBuilder buf = new StringBuilder();
+        buf.append("metric: ").append(metric);
+        buf.append(" tags: ").append(tags);
+        buf.append(" timestamp: ").append(timestamp);
+        buf.append(" count: ").append(count());
+        buf.append(" min: ").append(min());
+        buf.append(" max: ").append(max());
+        buf.append(" sum: ").append(sum());
+        buf.append(" 50p: ").append(getPercentile(50));
+        buf.append(" 75p: ").append(getPercentile(75));
+        buf.append(" 99p: ").append(getPercentile(99));
+        return buf.toString();
+    }
+
+    public byte[] serialize(MetricHistogram histo) {
+        StringBuilder buf = new StringBuilder();
+
+        String tags = histo.getTags().stream().map(t -> t.join()).collect(Collectors.joining(" "));
+
+        // @formatter:off
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.min())
+            .append(SPACE).append(tags).append(MIN);
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.max())
+            .append(SPACE).append(tags).append(MAX);
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.count())
+            .append(SPACE).append(tags).append(COUNT);
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.sum())
+            .append(SPACE).append(tags).append(SUM);
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.avg())
+            .append(SPACE).append(tags).append(AVG);
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.getPercentile(50))
+            .append(SPACE).append(tags).append(p50);
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.getPercentile(75))
+            .append(SPACE).append(tags).append(p75);
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.getPercentile(90))
+            .append(SPACE).append(tags).append(p90);
+        buf.append("put ").append(histo.getMetric() + "_summarized")
+            .append(SPACE).append(histo.getTimestamp())
+            .append(SPACE).append(histo.getPercentile(99))
+            .append(SPACE).append(tags).append(p99);
+        // @formatter:off
+        return buf.toString().getBytes();
+    }
+
+}

analytics/src/main/java/timely/analytics/flink/MetricKeySelector.java

@@ -0,0 +1,19 @@
+package timely.analytics.flink;
+
+import org.apache.flink.api.java.functions.KeySelector;
+import timely.api.response.MetricResponse;
+
+/**
+ * Uniquely defines a time series in a Flink stream. A unique time series is the
+ * metric name and all of its tags, to include visibility if it exists.
+ */
+public class MetricKeySelector implements KeySelector<MetricResponse, String> {
+
+    private static final long serialVersionUID = 1L;
+
+    @Override
+    public String getKey(MetricResponse m) throws Exception {
+        return m.getMetric() + m.getTags().toString();
+    }
+
+}

analytics/src/main/java/timely/analytics/flink/SortedStringAccumulator.java

@@ -0,0 +1,55 @@
+package timely.analytics.flink;
+
+import java.util.concurrent.ConcurrentSkipListMap;
+
+import org.apache.commons.lang3.mutable.MutableLong;
+import org.apache.flink.api.common.accumulators.Accumulator;
+
+/**
+ * Custom accumulator that retains a sorted map of strings and their counts
+ *
+ */
+public class SortedStringAccumulator implements Accumulator<String, ConcurrentSkipListMap<String, MutableLong>> {
+
+    private static final long serialVersionUID = 1L;
+
+    private ConcurrentSkipListMap<String, MutableLong> values = new ConcurrentSkipListMap<>();
+
+    @Override
+    public void add(String value) {
+        if (values.containsKey(value)) {
+            values.get(value).increment();
+        } else {
+            values.put(value, new MutableLong(1));
+        }
+    }
+
+    @Override
+    public ConcurrentSkipListMap<String, MutableLong> getLocalValue() {
+        return values;
+    }
+
+    @Override
+    public void resetLocal() {
+        values.clear();
+    }
+
+    @Override
+    public void merge(Accumulator<String, ConcurrentSkipListMap<String, MutableLong>> other) {
+        other.getLocalValue().forEach((k, v) -> {
+            if (values.containsKey(k)) {
+                values.get(k).add(v.longValue());
+            } else {
+                values.put(k, v);
+            }
+        });
+    }
+
+    @Override
+    public Accumulator<String, ConcurrentSkipListMap<String, MutableLong>> clone() {
+        SortedStringAccumulator a = new SortedStringAccumulator();
+        a.getLocalValue().putAll(this.values);
+        return a;
+    }
+
+}

analytics/src/main/java/timely/analytics/flink/SubscriptionSource.java

@@ -0,0 +1,217 @@
+package timely.analytics.flink;
+
+import java.io.IOException;
+import java.io.Serializable;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.RejectedExecutionException;
+import java.util.concurrent.ThreadFactory;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import javax.websocket.CloseReason;
+import javax.websocket.EndpointConfig;
+import javax.websocket.MessageHandler;
+import javax.websocket.Session;
+
+import org.apache.flink.api.common.accumulators.LongCounter;
+import org.apache.flink.api.common.functions.StoppableFunction;
+import org.apache.flink.configuration.Configuration;
+import org.apache.flink.streaming.api.functions.source.RichSourceFunction;
+import org.apache.flink.streaming.api.watermark.Watermark;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.api.response.MetricResponse;
+import timely.api.response.MetricResponses;
+import timely.client.websocket.ClientHandler;
+import timely.client.websocket.subscription.WebSocketSubscriptionClient;
+import timely.serialize.JsonSerializer;
+
+public class SubscriptionSource extends RichSourceFunction<MetricResponse> implements Serializable, StoppableFunction {
+
+    private static class SubscriptionThreadFactory implements ThreadFactory {
+
+        private static final String NAME = "Subscription Source";
+        private AtomicInteger threadNum = new AtomicInteger(1);
+
+        @Override
+        public Thread newThread(Runnable r) {
+            return new Thread(r, NAME + " " + threadNum.getAndIncrement());
+        }
+    }
+
+    private static final Logger LOG = LoggerFactory.getLogger(SubscriptionSource.class);
+    private static final long serialVersionUID = 1L;
+
+    private transient WebSocketSubscriptionClient client = null;
+    private long start = 0L;
+    private long end = 0L;
+    private final String[] metrics;
+    private final SummarizationJobParameters jp;
+    private final long window;
+    private final AtomicInteger subscriptionsRemaining;
+
+    public SubscriptionSource(SummarizationJobParameters jp) {
+        this.jp = jp;
+        start = jp.getStartTime();
+        end = jp.getEndTime();
+        metrics = jp.getMetrics();
+        window = jp.getSummarizationInterval().toMilliseconds();
+        subscriptionsRemaining = new AtomicInteger(metrics.length);
+    }
+
+    @Override
+    public void open(Configuration parameters) throws Exception {
+        LOG.info("Opening summarization job.");
+        super.open(parameters);
+        client = new WebSocketSubscriptionClient(jp.getTimelyHostname(), jp.getTimelyHttpsPort(), jp.getTimelyWssPort(),
+                jp.isClientAuth(), jp.isDoLogin(), jp.getTimelyUsername(), jp.getTimelyPassword(), jp.getKeyStoreFile(),
+                jp.getKeyStoreType(), jp.getKeyStorePass(), jp.getTrustStoreFile(), jp.getTrustStoreType(),
+                jp.getTrustStorePass(), jp.isHostVerificationEnabled(), jp.getBufferSize());
+    }
+
+    @Override
+    public synchronized void close() throws Exception {
+        super.close();
+        if (null != client) {
+            client.close();
+        }
+    }
+
+    @Override
+    public void run(SourceContext<MetricResponse> ctx) throws Exception {
+        LOG.info("Running summarization job");
+        final SortedStringAccumulator dateTimeAccumulator = new SortedStringAccumulator();
+        this.getRuntimeContext().addAccumulator("source hourly count", dateTimeAccumulator);
+        final LongCounter sourceInputs = new LongCounter();
+        this.getRuntimeContext().addAccumulator("source input counter", sourceInputs);
+        final LongCounter inputProcessedInMainThread = new LongCounter();
+        this.getRuntimeContext().addAccumulator("input processed in main thread", inputProcessedInMainThread);
+
+        // Use only one thread to ensure that time is still ordered
+        final ExecutorService svc = Executors.newFixedThreadPool(1, new SubscriptionThreadFactory());
+
+        ClientHandler handler = new ClientHandler() {
+
+            @Override
+            public void onOpen(Session session, EndpointConfig config) {
+                session.addMessageHandler(String.class, new MessageHandler.Whole<String>() {
+
+                    private final SimpleDateFormat formatter = new SimpleDateFormat("yyyyMMdd-HH");
+                    private long lastWatermarkTime = 0L;
+
+                    @Override
+                    public void onMessage(final String message) {
+                        LOG.info("Message received on Websocket session {}, length: {}", session.getId(),
+                                message.length());
+                        try {
+                            // Deserialize in this thread
+                            final MetricResponses responses = JsonSerializer.getObjectMapper().readValue(message,
+                                    MetricResponses.class);
+                            // Process in the other
+                            final Runnable r = () -> {
+                                responses.getResponses().forEach(response -> {
+                                    if (response.isComplete()) {
+                                        LOG.info("Received last message.");
+                                        ctx.emitWatermark(new Watermark(Long.MAX_VALUE));
+                                        subscriptionsRemaining.getAndDecrement();
+                                        return;
+                                    }
+                                    LOG.trace("Received metric: {}", response);
+                                    long time = response.getTimestamp();
+                                    ctx.collectWithTimestamp(response, time);
+                                    dateTimeAccumulator.add(formatter.format(new Date(response.getTimestamp())));
+                                    sourceInputs.add(1);
+                                    // Emit a watermark every second of event
+                                    // time
+                                    if (lastWatermarkTime == 0) {
+                                        lastWatermarkTime = time;
+                                    } else if ((time - lastWatermarkTime) > window) {
+                                        lastWatermarkTime = time;
+                                        ctx.emitWatermark(new Watermark(time - 1));
+                                    }
+                                });
+                            };
+                            try {
+                                svc.execute(r);
+                            } catch (RejectedExecutionException e) {
+                                // Run it in this thread
+                                r.run();
+                                inputProcessedInMainThread.add(1);
+                            }
+                        } catch (IOException e) {
+                            LOG.error("Error deserializing metric response, closing", e);
+                            try {
+                                close();
+                            } catch (Exception e1) {
+                                LOG.error("Error closing client", e1);
+                            }
+                        }
+                    }
+                });
+            }
+
+            @Override
+            public void onClose(Session session, CloseReason reason) {
+                super.onClose(session, reason);
+                try {
+                    close();
+                } catch (Exception e1) {
+                    LOG.error("Error closing client", e1);
+                }
+                // Signal done sending data
+                ctx.emitWatermark(new Watermark(Long.MAX_VALUE));
+            }
+
+            @Override
+            public void onError(Session session, Throwable error) {
+                super.onError(session, error);
+                try {
+                    close();
+                } catch (Exception e1) {
+                    LOG.error("Error closing client", e1);
+                }
+            }
+
+        };
+        try {
+            client.open(handler);
+            for (String m : metrics) {
+                LOG.info("Adding subscription for {}", m);
+                client.addSubscription(m, null, start, end, 5000);
+            }
+            while (!client.isClosed() && subscriptionsRemaining.get() > 0) {
+                try {
+                    Thread.sleep(5000);
+                } catch (InterruptedException e) {
+                    LOG.error("Sleep interrupted.");
+                }
+            }
+        } finally {
+            svc.shutdown();
+        }
+    }
+
+    @Override
+    public void cancel() {
+        LOG.info("Cancelling subscription source.");
+        try {
+            close();
+        } catch (Exception e) {
+            LOG.error("Error closing web socket client");
+        }
+    }
+
+    @Override
+    public void stop() {
+        LOG.info("Stopping subscription source.");
+        try {
+            close();
+        } catch (Exception e) {
+            LOG.error("Error closing web socket client");
+        }
+
+    }
+
+}

analytics/src/main/java/timely/analytics/flink/SummarizationJob.java

@@ -0,0 +1,108 @@
+package timely.analytics.flink;
+
+import java.text.SimpleDateFormat;
+import java.util.Date;
+
+import org.apache.flink.api.common.accumulators.LongCounter;
+import org.apache.flink.api.common.functions.FoldFunction;
+import org.apache.flink.api.java.utils.ParameterTool;
+import org.apache.flink.configuration.Configuration;
+import org.apache.flink.streaming.api.TimeCharacteristic;
+import org.apache.flink.streaming.api.environment.StreamExecutionEnvironment;
+import org.apache.flink.streaming.api.functions.sink.SocketClientSink;
+import org.apache.flink.streaming.api.windowing.assigners.TumblingEventTimeWindows;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.api.response.MetricResponse;
+
+public class SummarizationJob {
+
+    private static final Logger LOG = LoggerFactory.getLogger(SummarizationJob.class);
+
+    public static void main(String[] args) throws Exception {
+
+        if (args.length != 1) {
+            System.err.println("Usage: timely.analytics.flink.SummarizationJob <path_to_properties_file>");
+            System.exit(1);
+        }
+
+        LOG.info("Loading properties from: {}", args[0]);
+        ParameterTool params = ParameterTool.fromPropertiesFile(args[0]);
+
+        final SummarizationJobParameters jp = new SummarizationJobParameters(params);
+        LOG.info("Properties: {}", jp);
+
+        final StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment();
+        // @formatter:off
+        env.getConfig().setGlobalJobParameters(jp);
+        env.setStreamTimeCharacteristic(TimeCharacteristic.EventTime);
+        env.addSource(new SubscriptionSource(jp), "Timely Metrics Subscription")
+        // partition by unique metric
+        .keyBy(new MetricKeySelector())
+        .window(TumblingEventTimeWindows.of(jp.getSummarizationInterval()))
+        .fold(new MetricHistogram(), new FoldFunction<MetricResponse, MetricHistogram>() {
+
+            private final Logger LOG = LoggerFactory
+                    .getLogger("timely.analytics.SummarizationJob.FoldFunction@");
+            private static final long serialVersionUID = 1L;
+
+            @Override
+            public MetricHistogram fold(MetricHistogram histo, MetricResponse metric) throws Exception {
+                if (!histo.isInitialized()) {
+                    histo.initialize(metric.getMetric(), metric.getTags());
+                } else {
+                    if (!histo.getMetric().equals(metric.getMetric())) {
+                        throw new RuntimeException("Metric name does not match - partitioning problem");
+                    }
+                    if (!histo.getTags().equals(metric.getTags())) {
+                        throw new RuntimeException("Tags don't not match - partitioning problem");
+                    }
+                }
+                LOG.trace("Updating histogram for {} with value {} at {} for metric {}", histo.getMetric()
+                        + histo.getTags(), metric.getValue(), metric.getTimestamp(), metric.getMetric()
+                        + metric.getTags());
+                histo.update(metric.getValue(), metric.getTimestamp());
+                return histo;
+            }
+        })
+        .name("Metric Windows")
+        .addSink(
+            new SocketClientSink<MetricHistogram>(jp.getTimelyHostname(), jp.getTimelyTcpPort(),
+                    new MetricHistogram(), 2, true) {
+
+                private final Logger LOG = LoggerFactory
+                        .getLogger("timely.analytics.SummarizationJob.SocketClientSink");
+                private static final long serialVersionUID = 1L;
+                private final LongCounter sinkCounter = new LongCounter();
+                private final SortedStringAccumulator dateTimeAccumulator = new SortedStringAccumulator();
+                private final SimpleDateFormat formatter = new SimpleDateFormat("yyyyMMdd-HH");
+
+                @Override
+                public void open(Configuration parameters) throws Exception {
+                    super.open(parameters);
+                    this.getRuntimeContext().addAccumulator("sink counter", this.sinkCounter);
+                    this.getRuntimeContext().addAccumulator("sink hourly count", dateTimeAccumulator);
+                    LOG.info("Sink opened");
+                }
+
+                @Override
+                public void invoke(MetricHistogram histo) throws Exception {
+                    histo.done();
+                    super.invoke(histo);
+                    this.sinkCounter.add(1);
+                    this.dateTimeAccumulator.add(formatter.format(new Date(histo.getTimestamp())));
+                }
+
+                @Override
+                public void close() throws Exception {
+                    super.close();
+                    LOG.info("Sink closed");
+                }
+
+            }).name("Timely Metric Sink");
+        // @formatter:on
+        env.execute("Metric Summarization");
+        // Looks like there is no way to stop Flink job if underlying web socket
+        // is closed.
+    }
+}

analytics/src/main/java/timely/analytics/flink/SummarizationJobParameters.java

@@ -0,0 +1,215 @@
+package timely.analytics.flink;
+
+import java.io.Serializable;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+import org.apache.flink.api.common.ExecutionConfig.GlobalJobParameters;
+import org.apache.flink.api.java.utils.ParameterTool;
+import org.apache.flink.configuration.Configuration;
+import org.apache.flink.streaming.api.windowing.time.Time;
+
+public class SummarizationJobParameters extends GlobalJobParameters implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    private final String timelyHostname;
+    private final int timelyTcpPort;
+    private final int timelyHttpsPort;
+    private final int timelyWssPort;
+    private final boolean clientAuth;
+    private final boolean doLogin;
+    private final String timelyUsername;
+    private final String timelyPassword;
+    private final String keyStoreFile;
+    private final String keyStoreType;
+    private final String keyStorePass;
+    private final String trustStoreFile;
+    private final String trustStoreType;
+    private final String trustStorePass;
+    private final boolean hostVerificationEnabled;
+    private final int bufferSize;
+    private final String[] metrics;
+    private final long startTime;
+    private final long endTime;
+    private final String interval;
+    private final String intervalUnits;
+
+    public SummarizationJobParameters(ParameterTool params) {
+        timelyHostname = params.getRequired("timelyHostname");
+        timelyTcpPort = params.getInt("timelyTcpPort", 4241);
+        timelyHttpsPort = params.getInt("timelyHttpsPort", 4242);
+        timelyWssPort = params.getInt("timelyWssPort", 4243);
+        clientAuth = params.getBoolean("clientAuth", false);
+        doLogin = params.getBoolean("doLogin", false);
+        timelyUsername = params.get("timelyUsername", null);
+        timelyPassword = params.get("timelyPassword", null);
+        keyStoreFile = params.getRequired("keyStoreFile");
+        keyStoreType = params.get("keyStoreType", "JKS");
+        keyStorePass = params.getRequired("keyStorePass");
+        trustStoreFile = params.getRequired("trustStoreFile");
+        trustStoreType = params.get("trustStoreType", "JKS");
+        trustStorePass = params.getRequired("trustStorePass");
+        hostVerificationEnabled = params.getBoolean("hostVerificationEnabled", true);
+        bufferSize = params.getInt("bufferSize", 10485760);
+        String metricNames = params.getRequired("metrics");
+        if (null != metricNames) {
+            metrics = metricNames.split(",");
+        } else {
+            metrics = null;
+        }
+        startTime = params.getLong("startTime", 0L);
+        endTime = params.getLong("endTime", 0L);
+        interval = params.getRequired("interval");
+        intervalUnits = params.getRequired("intervalUnits");
+    }
+
+    public SummarizationJobParameters(Configuration conf) {
+        System.out.println("Creating job parameters from configuration: " + conf);
+        timelyHostname = conf.getString("timelyHostname", null);
+        timelyTcpPort = conf.getInteger("timelyTcpPort", 4241);
+        timelyHttpsPort = conf.getInteger("timelyHttpsPort", 4242);
+        timelyWssPort = conf.getInteger("timelyWssPort", 4243);
+        clientAuth = conf.getBoolean("clientAuth", false);
+        doLogin = conf.getBoolean("doLogin", false);
+        timelyUsername = conf.getString("timelyUsername", null);
+        timelyPassword = conf.getString("timelyPassword", null);
+        keyStoreFile = conf.getString("keyStoreFile", null);
+        keyStoreType = conf.getString("keyStoreType", "JKS");
+        keyStorePass = conf.getString("keyStorePass", null);
+        trustStoreFile = conf.getString("trustStoreFile", null);
+        trustStoreType = conf.getString("trustStoreType", "JKS");
+        trustStorePass = conf.getString("trustStorePass", null);
+        hostVerificationEnabled = conf.getBoolean("hostVerificationEnabled", true);
+        bufferSize = conf.getInteger("bufferSize", 10485760);
+        String metricNames = conf.getString("metrics", null);
+        if (null != metricNames) {
+            metrics = metricNames.split(",");
+        } else {
+            metrics = null;
+        }
+        startTime = conf.getLong("startTime", 0L);
+        endTime = conf.getLong("endTime", 0L);
+        interval = conf.getString("interval", null);
+        intervalUnits = conf.getString("intervalUnits", null);
+    }
+
+    public Time getSummarizationInterval() {
+        return Time.of(Long.parseLong(interval), TimeUnit.valueOf(intervalUnits));
+    }
+
+    public String getTimelyHostname() {
+        return timelyHostname;
+    }
+
+    public int getTimelyTcpPort() {
+        return timelyTcpPort;
+    }
+
+    public int getTimelyHttpsPort() {
+        return timelyHttpsPort;
+    }
+
+    public int getTimelyWssPort() {
+        return timelyWssPort;
+    }
+
+    public boolean isClientAuth() {
+        return clientAuth;
+    }
+
+    public boolean isDoLogin() {
+        return doLogin;
+    }
+
+    public String getTimelyUsername() {
+        return timelyUsername;
+    }
+
+    public String getTimelyPassword() {
+        return timelyPassword;
+    }
+
+    public String getKeyStoreFile() {
+        return keyStoreFile;
+    }
+
+    public String getKeyStoreType() {
+        return keyStoreType;
+    }
+
+    public String getKeyStorePass() {
+        return keyStorePass;
+    }
+
+    public String getTrustStoreFile() {
+        return trustStoreFile;
+    }
+
+    public String getTrustStoreType() {
+        return trustStoreType;
+    }
+
+    public String getTrustStorePass() {
+        return trustStorePass;
+    }
+
+    public boolean isHostVerificationEnabled() {
+        return hostVerificationEnabled;
+    }
+
+    public int getBufferSize() {
+        return bufferSize;
+    }
+
+    public String[] getMetrics() {
+        return metrics;
+    }
+
+    public long getStartTime() {
+        return startTime;
+    }
+
+    public long getEndTime() {
+        return endTime;
+    }
+
+    public String getInterval() {
+        return interval;
+    }
+
+    public String getIntervalUnits() {
+        return intervalUnits;
+    }
+
+    @Override
+    public Map<String, String> toMap() {
+        Map<String, String> m = new HashMap<>();
+        m.put("timelyHostname", this.timelyHostname);
+        m.put("timelyHttpsPort", Integer.toString(this.timelyHttpsPort));
+        m.put("timelyWssPort", Integer.toString(this.timelyWssPort));
+        m.put("doLogin", Boolean.toString(this.doLogin));
+        m.put("timelyUsername", this.timelyUsername);
+        m.put("timelyPassword", this.timelyPassword);
+        m.put("keyStoreFile", this.keyStoreFile);
+        m.put("keyStoreType", this.keyStoreType);
+        m.put("keyStorePass", this.keyStorePass);
+        m.put("trustStoreFile", this.trustStoreFile);
+        m.put("trustStoreType", this.trustStoreType);
+        m.put("trustStorePass", this.trustStorePass);
+        m.put("hostVerificationEnabled", Boolean.toString(this.hostVerificationEnabled));
+        m.put("bufferSize", Integer.toString(this.bufferSize));
+        m.put("metrics", String.join(",", this.metrics));
+        m.put("startTime", Long.toString(this.startTime));
+        m.put("endTime", Long.toString(this.endTime));
+        m.put("interval", this.interval);
+        m.put("intervalUnits", this.intervalUnits);
+        return m;
+    }
+
+    @Override
+    public String toString() {
+        return toMap().toString();
+    }
+}

analytics/src/main/spotbugs/excludes.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<FindBugsFilter>
+  <Match>
+    <Class name="timely.analytics.flink.MetricHistogram" />
+    <Method name="serialize" />
+    <Bug pattern="DM_DEFAULT_ENCODING" />
+  </Match>
+  <Match>
+    <Class name="timely.analytics.flink.SortedStringAccumulator" />
+    <Method name="clone" />
+    <Bug pattern="CN_IDIOM_NO_SUPER_CALL" />
+  </Match>
+  <Match>
+    <Class name="timely.analytics.flink.SummarizationJobParameters" />
+    <Method name="getMetrics" />
+    <Bug pattern="EI_EXPOSE_REP" />
+  </Match>
+</FindBugsFilter>

analytics/src/test/java/timely/analytics/flink/MetricHistogramTest.java

@@ -0,0 +1,106 @@
+package timely.analytics.flink;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+import timely.model.Metric;
+import timely.model.Tag;
+import timely.model.parse.MetricParser;
+
+public class MetricHistogramTest {
+
+    private MetricHistogram m = null;
+    private long timestamp = System.currentTimeMillis();
+
+    @Before
+    public void createMetric() throws Exception {
+        m = new MetricHistogram();
+        for (double d = 1.0D; d <= 100.0; d += 1.0) {
+            timestamp += 1000;
+            m.update(d, timestamp);
+        }
+        m.toString();
+        Assert.assertEquals(timestamp, m.getTimestamp());
+    }
+
+    @Test
+    public void testMin() throws Exception {
+        Assert.assertEquals(1.0D, m.min(), 0.0D);
+    }
+
+    @Test
+    public void testMax() throws Exception {
+        Assert.assertEquals(100.0D, m.max(), 0.0D);
+    }
+
+    @Test
+    public void testAvg() throws Exception {
+        int sum = 0;
+        for (int i = 1; i <= 100; i++) {
+            sum += i;
+        }
+        Assert.assertEquals((sum / 100.0D), m.avg(), 0.0D);
+    }
+
+    @Test
+    public void testCount() throws Exception {
+        Assert.assertEquals(100.0D, m.count(), 0.0D);
+    }
+
+    @Test
+    public void test50thPercentile() throws Exception {
+        Assert.assertEquals(50.0D, m.getPercentile(50), 0.0D);
+    }
+
+    @Test
+    public void test75thPercentile() throws Exception {
+        Assert.assertEquals(75.0D, m.getPercentile(75), 0.0D);
+    }
+
+    @Test
+    public void test90thPercentile() throws Exception {
+        Assert.assertEquals(90.0D, m.getPercentile(90), 0.0D);
+    }
+
+    @Test
+    public void test99thPercentile() throws Exception {
+        Assert.assertEquals(99.0D, m.getPercentile(99), 0.0D);
+    }
+
+    @Test
+    public void testSerialization() throws Exception {
+        MetricParser metricParser = new MetricParser();
+        Tag t1 = new Tag("tag1=value1");
+        Tag t2 = new Tag("tag2=value2");
+        Tag avg = new Tag("sample=avg");
+        Tag min = new Tag("sample=min");
+        Tag max = new Tag("sample=max");
+        Tag sum = new Tag("sample=sum");
+        Tag count = new Tag("sample=count");
+        Tag p50 = new Tag("sample=50p");
+        Tag p75 = new Tag("sample=75p");
+        Tag p90 = new Tag("sample=90p");
+        Tag p99 = new Tag("sample=99p");
+
+        List<Tag> tags = new ArrayList<>();
+        tags.add(t1);
+        tags.add(t2);
+        m.initialize("sys.cpu.user", tags);
+
+        byte[] bytes = m.serialize(m);
+        String puts = new String(bytes);
+        for (String put : puts.split("\n")) {
+            Metric metric = metricParser.parse(put);
+            Assert.assertEquals("sys.cpu.user_summarized", metric.getName());
+            metric.getTags().forEach(t -> {
+                Assert.assertTrue(
+                        t.equals(t1) || t.equals(t2) || t.equals(avg) || t.equals(min) || t.equals(max) || t.equals(sum)
+                                || t.equals(count) || t.equals(p50) || t.equals(p75) || t.equals(p90) || t.equals(p99));
+            });
+        }
+    }
+
+}

balancer/bin/testing/load-test-env.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+export TRUSTSTORE_FILE=
+export TRUSTSTORE_TYPE="jks";
+export TRUSTSTORE_PASS=
+export KEYSTORE_FILE=
+export KEYSTORE_TYPE="pkcs12";
+export KEYSTORE_PASS=
+
+export NUM_QUERY_THREADS=4
+export NUM_INGEST_THREADS=4

balancer/bin/testing/load-test-ingest.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+if [[ `uname` == "Darwin" ]]; then
+        THIS_SCRIPT=`python -c 'import os,sys; print os.path.realpath(sys.argv[1])' $0`
+else
+        THIS_SCRIPT=`readlink -f $0`
+fi
+
+THIS_DIR="${THIS_SCRIPT%/*}"
+BASE_DIR=${THIS_DIR}/../..
+TMP_DIR="${BASE_DIR}/tmp"
+CONF_DIR="${BASE_DIR}/conf"
+LIB_DIR="${BASE_DIR}/lib"
+
+. ${THIS_DIR}/load-test-env.sh
+
+export CLASSPATH="${CONF_DIR}:${THIS_DIR}:${LIB_DIR}/*"
+JVM_ARGS="-Xmx1G -Xms1G"
+
+echo "$JAVA_HOME/bin/java ${JVM_ARGS} timely.testing.MetricPutLoadTest $*"
+$JAVA_HOME/bin/java ${JVM_ARGS} timely.testing.MetricPutLoadTest $*

balancer/bin/testing/load-test-query.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+if [[ `uname` == "Darwin" ]]; then
+        THIS_SCRIPT=`python -c 'import os,sys; print os.path.realpath(sys.argv[1])' $0`
+else
+        THIS_SCRIPT=`readlink -f $0`
+fi
+
+THIS_DIR="${THIS_SCRIPT%/*}"
+BASE_DIR=${THIS_DIR}/../..
+TMP_DIR="${BASE_DIR}/tmp"
+CONF_DIR="${BASE_DIR}/conf"
+LIB_DIR="${BASE_DIR}/lib"
+
+. ${THIS_DIR}/load-test-env.sh
+
+export CLASSPATH="${CONF_DIR}:${THIS_DIR}:${LIB_DIR}/*"
+JVM_ARGS="-Xmx1G -Xms1G"
+
+echo "$JAVA_HOME/bin/java ${JVM_ARGS} timely.testing.MetricQueryLoadTest $*"
+$JAVA_HOME/bin/java ${JVM_ARGS} timely.testing.MetricQueryLoadTest $*

balancer/bin/testing/load-test-unique.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+if [[ `uname` == "Darwin" ]]; then
+        THIS_SCRIPT=`python -c 'import os,sys; print os.path.realpath(sys.argv[1])' $0`
+else
+        THIS_SCRIPT=`readlink -f $0`
+fi
+
+THIS_DIR="${THIS_SCRIPT%/*}"
+
+sed -i -- "s/#.*#/#$1#/g" $THIS_DIR/load-test-data.txt

balancer/bin/timely-balancer.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+if [[ `uname` == "Darwin" ]]; then
+        THIS_SCRIPT=`python -c 'import os,sys; print os.path.realpath(sys.argv[1])' $0`
+        TCNATIVE_SUFFIX="jnilib"
+else
+        THIS_SCRIPT=`readlink -f $0`
+        TCNATIVE_SUFFIX="so"
+fi
+
+THIS_DIR="${THIS_SCRIPT%/*}"
+NATIVE_DIR="${THIS_DIR}/META-INF/native"
+BASE_DIR=${THIS_DIR}/..
+TMP_DIR="${BASE_DIR}/tmp"
+CONF_DIR="${BASE_DIR}/conf"
+LIB_DIR="${BASE_DIR}/lib"
+NUM_SERVER_THREADS=4
+
+if [[ -e ${TMP_DIR} ]]; then
+  rm -rf ${TMP_DIR}
+fi
+mkdir ${TMP_DIR}
+
+if [[ -e ${NATIVE_DIR} ]]; then
+  rm -rf ${NATIVE_DIR}
+fi
+mkdir -p ${NATIVE_DIR}
+
+pushd ${BASE_DIR}/bin
+$JAVA_HOME/bin/jar xf ${LIB_DIR}/netty-tcnative-boringssl-static*.jar META-INF/native/libnetty_tcnative_linux_x86_64.${TCNATIVE_SUFFIX}
+$JAVA_HOME/bin/jar xf ${LIB_DIR}/netty-all*.jar META-INF/native/libnetty_transport_native_epoll_x86_64.${TCNATIVE_SUFFIX}
+popd
+
+export CLASSPATH="${CONF_DIR}:${LIB_DIR}/*:${HADOOP_CONF_DIR}"
+JVM_ARGS="-Xmx1G -Xms1G -Dio.netty.eventLoopThreads=${NUM_SERVER_THREADS} -Dlog4j.configurationFile=${CONF_DIR}/log4j2-spring.xml"
+JVM_ARGS="${JVM_ARGS} -DLog4jContextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector"
+JVM_ARGS="${JVM_ARGS} -Djava.library.path=${NATIVE_DIR}"
+
+#JVM_ARGS="${JVM_ARGS} -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"
+
+echo "$JAVA_HOME/bin/java ${JVM_ARGS} timely.balancer.Balancer --spring.config.name=timely --spring.profiles.active=balancer"
+$JAVA_HOME/bin/java ${JVM_ARGS} timely.balancer.Balancer --spring.config.name=timely --spring.profiles.active=balancer

balancer/conf/log4j2-error-console.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="warn" monitorInterval="60">
+  <Appenders>
+    <Console name="Console" target="SYSTEM_OUT">
+      <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
+    </Console>
+  </Appenders>
+  <Loggers>
+    <Root level="error" includeLocation="false">
+      <AppenderRef ref="Console" level="error" />
+    </Root>
+  </Loggers>
+</Configuration>

balancer/conf/log4j2-spring.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="warn" monitorInterval="60">
+  <Properties>
+    <Property name="PID">????</Property>
+    <Property name="LOG_PATTERN">%clr{%d{yyyy-MM-dd HH:mm:ss.SSS}}{faint} %clr{%5p} %clr{${sys:PID}}{magenta} %clr{---}{faint} %clr{[%15.15t]}{faint} %clr{%-40.40c{1.}}{cyan} %clr{:}{faint} %m%n%wEx</Property>
+  </Properties>
+  <Appenders>
+    <RollingRandomAccessFile name="Rolling" fileName="/srv/logs/timely/timely-balancer.log"
+    						 filePattern="/srv/logs/timely/$${date:yyyy-MM}/timely-balancer-%d{MM-dd-yyyy}-%i.log.gz">
+      <PatternLayout pattern="${LOG_PATTERN}"/>
+      <Policies>
+      	<SizeBasedTriggeringPolicy size="1024 MB" />
+      </Policies>
+      <DefaultRolloverStrategy max="10" />
+    </RollingRandomAccessFile>
+    <Console name="Console" target="SYSTEM_OUT">
+      <PatternLayout pattern="${LOG_PATTERN}"/>
+    </Console>
+  </Appenders>
+  <Loggers>
+    <Root level="trace" includeLocation="false">
+      <AppenderRef ref="Console" level="warn" />
+      <AppenderRef ref="Rolling" level="trace" />
+    </Root>
+    <Logger name="timely" additivity="false">
+      <AppenderRef ref="Console" level="debug" />
+    </Logger>
+  </Loggers>
+</Configuration>

balancer/conf/security.xml

@@ -0,0 +1,71 @@
+<beans:beans xmlns="http://www.springframework.org/schema/security"
+             xmlns:beans="http://www.springframework.org/schema/beans"
+             xmlns:util="http://www.springframework.org/schema/util"
+             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+             xsi:schemaLocation="http://www.springframework.org/schema/beans
+								 http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+								 http://www.springframework.org/schema/security
+								 http://www.springframework.org/schema/security/spring-security.xsd
+								 http://www.springframework.org/schema/util
+								 http://www.springframework.org/schema/util/spring-util.xsd">
+		          
+	<beans:bean id="x509PrincipalExtractor" class="org.springframework.security.web.authentication.preauth.x509.SubjectDnX509PrincipalExtractor">
+		<beans:property name="subjectDnRegex" value="CN=(.*?)(?:,|$)"/>
+	</beans:bean>
+
+	<beans:bean id="timelyUserDetailsService" class="timely.auth.UserDetailsService">
+		<beans:property name="users">
+			<util:list>
+				<beans:bean class="timely.auth.TimelyUser">
+					<beans:constructor-arg name="subjectDn">
+						<beans:value>CN=example.com</beans:value>
+					</beans:constructor-arg>
+					<beans:constructor-arg name="auths">
+						<util:list>
+							<beans:value>D</beans:value>
+							<beans:value>E</beans:value>
+							<beans:value>F</beans:value>
+						</util:list>
+					</beans:constructor-arg>
+					<beans:constructor-arg name="roles">
+						<util:list>
+							<beans:value>G</beans:value>
+							<beans:value>H</beans:value>
+							<beans:value>I</beans:value>
+						</util:list>
+					</beans:constructor-arg>
+				</beans:bean>
+			</util:list>
+		</beans:property>
+	</beans:bean>
+    
+    <beans:bean id="x509AuthorizationProvider" class="org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticationProvider">
+    	<beans:property name="preAuthenticatedUserDetailsService" ref="timelyUserDetailsService" />
+    </beans:bean>
+    
+    <user-service id="usernamePasswordService">
+    	<user name="test" password="test1" authorities="A,B,C" />
+    </user-service>
+
+	<beans:bean id="noOpPasswordEncoder" class="org.springframework.security.crypto.password.NoOpPasswordEncoder"/>
+
+	<beans:bean id="UserNamePasswordAuthenticationProvider" class="org.springframework.security.authentication.dao.DaoAuthenticationProvider">
+		<beans:property name="userDetailsService" ref="usernamePasswordService"/>
+		<beans:property name="passwordEncoder" ref="noOpPasswordEncoder"/>
+	</beans:bean>
+	    
+	<authentication-manager alias="authenticationManager">
+		<!-- X509 PreAuthenticated authorization provider -->
+		<authentication-provider ref="x509AuthorizationProvider"/>
+		<!-- Basic authorization provider, validates provided username and password -->
+		<authentication-provider ref="UserNamePasswordAuthenticationProvider" />
+	</authentication-manager>
+
+	<util:list id="requiredRoles" value-type="java.lang.String">
+		<beans:value></beans:value>
+	</util:list>
+
+	<util:list id="requiredAuths" value-type="java.lang.String">
+		<beans:value></beans:value>
+	</util:list>
+</beans:beans>

balancer/conf/timely-balancer.yml

@@ -0,0 +1,131 @@
+timely-balancer:
+  zooKeeper:
+    servers: localhost:2181
+    timeout: 30s
+  checkServerHealthInterval: 10000
+  serverFailuresBeforeDown: 6
+  serverSuccessesBeforeUp: 1
+  assignmentFile: /timely/balancer/assignments.csv
+  security:
+    session-max-age: 86400
+    cache-expiration-minutes: 60
+    cache-refresh-minutes: 5
+    allow-anonymous-http-access: true
+    allow-anonymous-ws-access: true
+    serverSsl:
+      certificate-file:
+      key-file:
+      #key-password:
+      use-generated-keypair: true
+      trust-store-file:
+      use-openssl: true
+      #use-ciphers:
+    clientSsl:
+      keyFile:
+      keyType: pkcs12
+      #keyPassword:
+      trustStoreFile:
+      trustStoreType: jks
+      #trustStorePassword:
+  cache:
+    enabled: false
+    metric-age-off-hours:
+      default: 26
+    nonCachedMetrics:
+  server:
+    ip: 127.0.0.1
+    tcpPort: 4242
+    numTcpPools: 1
+    tcpBufferSize: 100
+    tcpClientPool:
+      minIdlePerKey: 0
+      maxIdlePerKey: 40
+      maxTotalPerKey: 40
+      maxTotal: -1
+      lifo: true
+      fairness: false
+      maxWaitMillis: -1
+      minEvictableIdleTimeMillis: 1800000
+      evictorShutdownTimeoutMillis: 10000
+      softMinEvictableIdleTimeMillis: -1
+      numTestsPerEvictionRun: 3
+      timeBetweenEvictionRunsMillis: -1
+      blockWhenExhausted: true
+      jmxEnabled: true
+      testOnBorrow: false
+      testOnReturn: false
+    udpPort: 4245
+    udpClientPool:
+      minIdlePerKey: 0
+      maxIdlePerKey: 40
+      maxTotalPerKey: 40
+      maxTotal: -1
+      lifo: true
+      fairness: false
+      maxWaitMillis: -1
+      minEvictableIdleTimeMillis: 1800000
+      evictorShutdownTimeoutMillis: 10000
+      softMinEvictableIdleTimeMillis: -1
+      numTestsPerEvictionRun: 3
+      timeBetweenEvictionRunsMillis: -1
+      blockWhenExhausted: true
+      jmxEnabled: true
+      testOnBorrow: false
+      testOnReturn: false
+  http:
+    host: localhost
+    ip: 127.0.0.1
+    port: 4243
+    redirect-path: /secure-me
+    strict-transport-max-age: 608400
+    cors:
+      allow-any-origin: false
+      allow-null-origin: false
+      allow-credentials: true
+      allowed-origins:
+      allowed-methods: DELETE,GET,HEAD,OPTIONS,PUT,POST
+      allowed-headers: content-type
+    httpClientPool:
+      minIdlePerKey: 0
+      maxIdlePerKey: 40
+      maxTotalPerKey: 40
+      maxTotal: -1
+      lifo: true
+      fairness: false
+      maxWaitMillis: -1
+      minEvictableIdleTimeMillis: 1800000
+      evictorShutdownTimeoutMillis: 10000
+      softMinEvictableIdleTimeMillis: -1
+      numTestsPerEvictionRun: 3
+      timeBetweenEvictionRunsMillis: -1
+      blockWhenExhausted: true
+      jmxEnabled: true
+      testOnBorrow: false
+      testOnReturn: false
+  websocket:
+    ip: 127.0.0.1
+    port: 5244
+    timeout: 60
+    subscription-lag: 120
+    scanner-batch-size: 10000
+    flush-interval-seconds: 30
+    scanner-read-ahead: 1
+    subscription-batch-size: 5000
+    incomingBufferSize: 50000000
+    wsClientPool:
+      minIdlePerKey: 0
+      maxIdlePerKey: 40
+      maxTotalPerKey: 40
+      maxTotal: -1
+      lifo: true
+      fairness: false
+      maxWaitMillis: -1
+      minEvictableIdleTimeMillis: 1800000
+      evictorShutdownTimeoutMillis: 10000
+      softMinEvictableIdleTimeMillis: -1
+      numTestsPerEvictionRun: 3
+      timeBetweenEvictionRunsMillis: -1
+      blockWhenExhausted: true
+      jmxEnabled: true
+      testOnBorrow: false
+      testOnReturn: false

balancer/pom.xml

@@ -0,0 +1,295 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>timely</groupId>
+    <artifactId>timely</artifactId>
+    <version>1.2.8-SNAPSHOT</version>
+  </parent>
+  <artifactId>timely-balancer</artifactId>
+  <dependencies>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-annotations</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-core</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.datatype</groupId>
+      <artifactId>jackson-datatype-jdk8</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.github.ben-manes.caffeine</groupId>
+      <artifactId>caffeine</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.google.flatbuffers</groupId>
+      <artifactId>flatbuffers-java</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>commons-beanutils</groupId>
+      <artifactId>commons-beanutils</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>io.github.lukehutch</groupId>
+      <artifactId>fast-classpath-scanner</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>io.netty</groupId>
+      <artifactId>netty-all</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>net.sourceforge.javacsv</groupId>
+      <artifactId>javacsv</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.accumulo</groupId>
+      <artifactId>accumulo-core</artifactId>
+      <exclusions>
+        <exclusion>
+          <groupId>org.slf4j</groupId>
+          <artifactId>slf4j-log4j12</artifactId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.accumulo</groupId>
+      <artifactId>accumulo-minicluster</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-collections4</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-lang3</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-pool2</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.curator</groupId>
+      <artifactId>curator-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.curator</groupId>
+      <artifactId>curator-framework</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.curator</groupId>
+      <artifactId>curator-recipes</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.curator</groupId>
+      <artifactId>curator-x-discovery</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.hadoop</groupId>
+      <artifactId>hadoop-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.hadoop</groupId>
+      <artifactId>hadoop-common</artifactId>
+      <exclusions>
+        <exclusion>
+          <groupId>jdk.tools</groupId>
+          <artifactId>jdk.tools</artifactId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.hadoop</groupId>
+      <artifactId>hadoop-minicluster</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.glassfish.tyrus</groupId>
+      <artifactId>tyrus-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-websocket</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter</artifactId>
+      <exclusions>
+        <exclusion>
+          <groupId>org.springframework.boot</groupId>
+          <artifactId>spring-boot-starter-logging</artifactId>
+        </exclusion>
+      </exclusions>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-log4j2</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-validation</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.security</groupId>
+      <artifactId>spring-security-config</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.security</groupId>
+      <artifactId>spring-security-web</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>timely</groupId>
+      <artifactId>timely-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>timely</groupId>
+      <artifactId>timely-common</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>timely</groupId>
+      <artifactId>timely-server</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.lmax</groupId>
+      <artifactId>disruptor</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>io.netty</groupId>
+      <artifactId>netty-tcnative-boringssl-static</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-api</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-core</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-slf4j-impl</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.javassist</groupId>
+      <artifactId>javassist</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.jsoup</groupId>
+      <artifactId>jsoup</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-test-autoconfigure</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>assemble</id>
+            <goals>
+              <goal>single</goal>
+            </goals>
+            <phase>package</phase>
+            <configuration>
+              <descriptors>
+                <descriptor>src/main/dist/assembly.xml</descriptor>
+              </descriptors>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>copy-dependencies</id>
+            <goals>
+              <goal>copy-dependencies</goal>
+            </goals>
+            <phase>prepare-package</phase>
+            <configuration>
+              <excludeArtifactIds>junit</excludeArtifactIds>
+              <outputDirectory>${project.build.directory}/lib</outputDirectory>
+            </configuration>
+          </execution>
+          <execution>
+            <id>unpack-native</id>
+            <goals>
+              <goal>unpack</goal>
+            </goals>
+            <phase>process-test-classes</phase>
+            <configuration>
+              <artifactItems>
+                <artifactItem>
+                  <groupId>io.netty</groupId>
+                  <artifactId>netty-tcnative-boringssl-static</artifactId>
+                  <version>${version.netty-tcnative}</version>
+                  <type>jar</type>
+                  <overWrite>false</overWrite>
+                  <outputDirectory>${project.build.directory}/native</outputDirectory>
+                  <includes>**/*.so</includes>
+                </artifactItem>
+              </artifactItems>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-failsafe-plugin</artifactId>
+      </plugin>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>build-helper-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>add-source</id>
+            <goals>
+              <goal>add-source</goal>
+            </goals>
+            <phase>generate-sources</phase>
+            <configuration>
+              <sources>
+                <source>src/main/generated-java</source>
+              </sources>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+    <extensions>
+      <!-- Use os-maven-plugin to initialize the "os.detected" properties -->
+      <extension>
+        <groupId>kr.motd.maven</groupId>
+        <artifactId>os-maven-plugin</artifactId>
+      </extension>
+    </extensions>
+  </build>
+</project>

balancer/src/main/dist/assembly.xml

@@ -0,0 +1,54 @@
+<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3" 
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
+  <id>dist</id>
+  <formats>
+    <format>tar.gz</format>
+  </formats>
+  <fileSets>
+    <fileSet>
+      <directory>${project.basedir}</directory>
+      <outputDirectory></outputDirectory>
+      <includes>
+        <include>README*</include>
+        <include>LICENSE*</include>
+        <include>NOTICE*</include>
+      </includes>
+    </fileSet>
+    <fileSet>
+      <directory>${project.build.directory}</directory>
+      <outputDirectory>lib</outputDirectory>
+      <includes>
+        <include>timely*.jar</include>
+      </includes>
+    </fileSet>
+    <fileSet>
+      <directory>${project.build.directory}/lib</directory>
+      <outputDirectory>lib</outputDirectory>
+      <includes>
+        <include>*.jar</include>
+      </includes>
+     </fileSet>
+    <fileSet>
+      <directory>${project.basedir}/bin</directory>
+      <outputDirectory>bin</outputDirectory>
+      <includes>
+        <include>**/*</include>
+      </includes>
+     </fileSet>
+    <fileSet>
+      <directory>${project.basedir}/conf</directory>
+      <outputDirectory>conf</outputDirectory>
+      <includes>
+        <include>*</include>
+      </includes>
+     </fileSet>
+	<fileSet>
+	  <directory>${project.basedir}/src/main/resources/webapp</directory>
+	  <outputDirectory>bin/webapp</outputDirectory>
+	  <includes>
+		<include>*</include>
+	  </includes>
+	</fileSet>
+  </fileSets>
+</assembly>

balancer/src/main/java/timely/balancer/ArrivalRate.java

@@ -0,0 +1,121 @@
+package timely.balancer;
+
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
+
+import com.google.common.util.concurrent.AtomicDouble;
+
+public class ArrivalRate {
+
+    private AtomicLong shortTermArrivals = new AtomicLong(0);
+    private AtomicDouble shortTermRate = new AtomicDouble(0);
+    private AtomicLong shortTermLastReset = new AtomicLong(0);
+
+    private AtomicLong mediumTermArrivals = new AtomicLong(0);
+    private AtomicDouble mediumTermRate = new AtomicDouble(0);
+    private AtomicLong mediumTermLastReset = new AtomicLong(0);
+
+    private AtomicLong longTermArrivals = new AtomicLong(0);
+    private AtomicDouble longTermRate = new AtomicDouble(0);
+    private AtomicLong longTermLastReset = new AtomicLong(0);
+
+    public ArrivalRate(ScheduledExecutorService arrivalRateExecutor) {
+        long now = System.currentTimeMillis();
+        shortTermLastReset.set(now);
+        mediumTermLastReset.set(now);
+        longTermLastReset.set(now);
+
+        // 2 minute
+        arrivalRateExecutor.scheduleAtFixedRate(() -> {
+            resetShort();
+        }, 2, 2, TimeUnit.MINUTES);
+
+        // 5 minute
+        arrivalRateExecutor.scheduleAtFixedRate(() -> {
+            resetMedium();
+        }, 5, 5, TimeUnit.MINUTES);
+
+        // 15 minute
+        arrivalRateExecutor.scheduleAtFixedRate(() -> {
+            resetLong();
+        }, 15, 15, TimeUnit.MINUTES);
+    }
+
+    private void resetShort() {
+        long now = System.currentTimeMillis();
+        long lastReset = shortTermLastReset.get();
+        if (now == lastReset) {
+            shortTermRate.set(0);
+        } else {
+            shortTermRate.set(shortTermArrivals.get() / (((double) (now - lastReset)) / 1000));
+        }
+        shortTermArrivals.set(0);
+        shortTermLastReset.set(now);
+    }
+
+    private void resetMedium() {
+        long now = System.currentTimeMillis();
+        long lastReset = mediumTermLastReset.get();
+        if (now == lastReset) {
+            mediumTermRate.set(0);
+        } else {
+            mediumTermRate.set(mediumTermArrivals.get() / (((double) (now - lastReset)) / 1000));
+        }
+        mediumTermArrivals.set(0);
+        mediumTermLastReset.set(now);
+    }
+
+    private void resetLong() {
+        long now = System.currentTimeMillis();
+        long lastReset = longTermLastReset.get();
+        if (now == lastReset) {
+            longTermRate.set(0);
+        } else {
+            longTermRate.set(longTermArrivals.get() / (((double) (now - lastReset)) / 1000));
+        }
+        longTermArrivals.set(0);
+        longTermLastReset.set(now);
+    }
+
+    public void arrived() {
+        shortTermArrivals.incrementAndGet();
+        mediumTermArrivals.incrementAndGet();
+        longTermArrivals.incrementAndGet();
+    }
+
+    private double getShortRate(long now) {
+        double rate = shortTermRate.get();
+        long lastReset = shortTermLastReset.get();
+        if (rate > 0 || now == lastReset) {
+            return rate;
+        } else {
+            return shortTermArrivals.get() / (((double) (now - lastReset)) / 1000);
+        }
+    }
+
+    private double getMediumRate(long now) {
+        double rate = mediumTermRate.get();
+        long lastReset = mediumTermLastReset.get();
+        if (rate > 0 || now == lastReset) {
+            return rate;
+        } else {
+            return mediumTermArrivals.get() / (((double) (now - lastReset)) / 1000);
+        }
+    }
+
+    private double getLongRate(long now) {
+        double rate = longTermRate.get();
+        long lastReset = longTermLastReset.get();
+        if (rate > 0 || now == lastReset) {
+            return rate;
+        } else {
+            return longTermArrivals.get() / (((double) (now - lastReset)) / 1000);
+        }
+    }
+
+    public double getRate() {
+        long now = System.currentTimeMillis();
+        return 0.10 * getLongRate(now) + 0.10 * getMediumRate(now) + 0.80 * getShortRate(now);
+    }
+}

balancer/src/main/java/timely/balancer/Balancer.java

@@ -0,0 +1,599 @@
+package timely.balancer;
+
+import static timely.Server.SERVICE_DISCOVERY_PATH;
+import static timely.store.cache.DataStoreCache.NON_CACHED_METRICS;
+import static timely.store.cache.DataStoreCache.NON_CACHED_METRICS_LOCK_PATH;
+
+import java.io.File;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Date;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+
+import javax.net.ssl.SSLContext;
+
+import io.netty.bootstrap.Bootstrap;
+import io.netty.bootstrap.ServerBootstrap;
+import io.netty.buffer.PooledByteBufAllocator;
+import io.netty.channel.Channel;
+import io.netty.channel.ChannelFuture;
+import io.netty.channel.ChannelHandler;
+import io.netty.channel.ChannelInitializer;
+import io.netty.channel.ChannelOption;
+import io.netty.channel.EventLoopGroup;
+import io.netty.channel.WriteBufferWaterMark;
+import io.netty.channel.epoll.EpollChannelOption;
+import io.netty.channel.epoll.EpollDatagramChannel;
+import io.netty.channel.epoll.EpollEventLoopGroup;
+import io.netty.channel.epoll.EpollServerSocketChannel;
+import io.netty.channel.nio.NioEventLoopGroup;
+import io.netty.channel.socket.DatagramChannel;
+import io.netty.channel.socket.ServerSocketChannel;
+import io.netty.channel.socket.SocketChannel;
+import io.netty.channel.socket.nio.NioDatagramChannel;
+import io.netty.channel.socket.nio.NioServerSocketChannel;
+import io.netty.handler.codec.DelimiterBasedFrameDecoder;
+import io.netty.handler.codec.Delimiters;
+import io.netty.handler.codec.http.HttpContentCompressor;
+import io.netty.handler.codec.http.HttpContentDecompressor;
+import io.netty.handler.codec.http.HttpObjectAggregator;
+import io.netty.handler.codec.http.HttpRequestDecoder;
+import io.netty.handler.codec.http.HttpResponseEncoder;
+import io.netty.handler.codec.http.HttpServerCodec;
+import io.netty.handler.codec.http.websocketx.WebSocketServerProtocolHandler;
+import io.netty.handler.logging.LoggingHandler;
+import io.netty.handler.ssl.ClientAuth;
+import io.netty.handler.ssl.OpenSslServerContext;
+import io.netty.handler.ssl.OpenSslServerSessionContext;
+import io.netty.handler.ssl.SslContext;
+import io.netty.handler.ssl.SslContextBuilder;
+import io.netty.handler.ssl.SslProvider;
+import io.netty.handler.ssl.util.SelfSignedCertificate;
+import io.netty.handler.stream.ChunkedWriteHandler;
+import io.netty.handler.timeout.IdleStateHandler;
+import io.netty.util.NettyRuntime;
+import io.netty.util.internal.SystemPropertyUtil;
+import org.apache.accumulo.core.conf.AccumuloConfiguration;
+import org.apache.curator.RetryPolicy;
+import org.apache.curator.framework.CuratorFramework;
+import org.apache.curator.framework.CuratorFrameworkFactory;
+import org.apache.curator.retry.RetryForever;
+import org.apache.zookeeper.CreateMode;
+import org.apache.zookeeper.data.Stat;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.boot.WebApplicationType;
+import org.springframework.boot.builder.SpringApplicationBuilder;
+import org.springframework.context.ConfigurableApplicationContext;
+import timely.auth.AuthCache;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.configuration.ClientSsl;
+import timely.balancer.configuration.SpringBootstrap;
+import timely.balancer.connection.http.HttpClientPool;
+import timely.balancer.connection.tcp.TcpClientPool;
+import timely.balancer.connection.udp.UdpClientPool;
+import timely.balancer.connection.ws.WsClientPool;
+import timely.balancer.healthcheck.TcpHealthChecker;
+import timely.balancer.netty.http.HttpRelayHandler;
+import timely.balancer.netty.tcp.TcpRelayHandler;
+import timely.balancer.netty.udp.UdpRelayHandler;
+import timely.balancer.netty.ws.WsRelayHandler;
+import timely.balancer.resolver.BalancedMetricResolver;
+import timely.balancer.resolver.MetricResolver;
+import timely.client.http.HttpClient;
+import timely.configuration.ServerSsl;
+import timely.netty.http.HttpStaticFileServerHandler;
+import timely.netty.http.NonSslRedirectHandler;
+import timely.netty.http.TimelyExceptionHandler;
+import timely.netty.http.auth.X509LoginRequestHandler;
+import timely.netty.tcp.MetricsBufferDecoder;
+import timely.netty.tcp.TcpDecoder;
+import timely.netty.tcp.TcpVersionHandler;
+import timely.netty.udp.UdpDecoder;
+import timely.netty.udp.UdpPacketToByteBuf;
+import timely.netty.websocket.WebSocketFullRequestHandler;
+import timely.netty.websocket.WebSocketRequestDecoder;
+import timely.netty.websocket.subscription.WSTimelyExceptionHandler;
+
+public class Balancer {
+
+    final public static String LEADER_LATCH_PATH = "/timely/balancer/leader";
+    final public static String ASSIGNMENTS_LOCK_PATH = "/timely/balancer/assignments/lock";
+    final public static String ASSIGNMENTS_LAST_UPDATED_PATH = "/timely/balancer/assignments/lastUpdated";
+
+    private static final Logger LOG = LoggerFactory.getLogger(Balancer.class);
+    private static final int EPOLL_MIN_MAJOR_VERSION = 2;
+    private static final int EPOLL_MIN_MINOR_VERSION = 6;
+    private static final int EPOLL_MIN_PATCH_VERSION = 32;
+    private static final String OS_NAME = "os.name";
+    private static final String OS_VERSION = "os.version";
+    private static final String WS_PATH = "/websocket";
+    protected static final CountDownLatch LATCH = new CountDownLatch(1);
+    static ConfigurableApplicationContext applicationContext;
+
+    private final BalancerConfiguration balancerConfig;
+    private EventLoopGroup tcpWorkerGroup = null;
+    private EventLoopGroup tcpBossGroup = null;
+    private EventLoopGroup httpWorkerGroup = null;
+    private EventLoopGroup httpBossGroup = null;
+    private EventLoopGroup wsWorkerGroup = null;
+    private EventLoopGroup wsBossGroup = null;
+    private EventLoopGroup udpBossGroup = null;
+    private EventLoopGroup udpWorkerGroup = null;
+    private MetricResolver metricResolver;
+    protected Channel tcpChannelHandle = null;
+    protected Channel httpChannelHandle = null;
+    protected Channel wsChannelHandle = null;
+    protected List<Channel> udpChannelHandleList = new ArrayList<>();
+    private CuratorFramework curatorFramework;
+    protected volatile boolean shutdown = false;
+    private static final int DEFAULT_EVENT_LOOP_THREADS;
+
+    private String[] zkPaths = new String[] { LEADER_LATCH_PATH, ASSIGNMENTS_LAST_UPDATED_PATH, ASSIGNMENTS_LOCK_PATH,
+            SERVICE_DISCOVERY_PATH, NON_CACHED_METRICS, NON_CACHED_METRICS_LOCK_PATH };
+
+    static {
+        DEFAULT_EVENT_LOOP_THREADS = Math.max(1,
+                SystemPropertyUtil.getInt("io.netty.eventLoopThreads", NettyRuntime.availableProcessors() * 2));
+    }
+
+    public Balancer(BalancerConfiguration balancerConf) throws Exception {
+        this.balancerConfig = balancerConf;
+    }
+
+    protected static ConfigurableApplicationContext initializeContext(String[] args) {
+        SpringApplicationBuilder builder = new SpringApplicationBuilder(SpringBootstrap.class);
+        builder.web(WebApplicationType.NONE);
+        builder.registerShutdownHook(false);
+        return builder.run(args);
+    }
+
+    private void shutdownHook() {
+
+        final Runnable shutdownRunner = () -> {
+            if (!shutdown) {
+                shutdown();
+            }
+        };
+        final Thread hook = new Thread(shutdownRunner, "shutdown-hook-thread");
+        Runtime.getRuntime().addShutdownHook(hook);
+    }
+
+    public void shutdown() {
+        List<ChannelFuture> channelFutures = new ArrayList<>();
+
+        if (tcpChannelHandle != null) {
+            LOG.info("Closing tcpChannelHandle");
+            channelFutures.add(tcpChannelHandle.close());
+        }
+
+        if (httpChannelHandle != null) {
+            LOG.info("Closing httpChannelHandle");
+            channelFutures.add(httpChannelHandle.close());
+        }
+
+        if (wsChannelHandle != null) {
+            LOG.info("Closing wsChannelHandle");
+            channelFutures.add(wsChannelHandle.close());
+        }
+
+        int udpChannel = 1;
+        for (Channel c : udpChannelHandleList) {
+            LOG.info("Closing udpChannelHandle #" + udpChannel++);
+            channelFutures.add(c.close());
+        }
+
+        // wait for the channels to shutdown
+        channelFutures.forEach(f -> {
+            try {
+                f.get();
+            } catch (final Exception e) {
+                LOG.error("Channel:" + f.channel().config() + " -> " + e.getMessage(), e);
+            }
+        });
+
+        int quietPeriod = balancerConfig.getServer().getShutdownQuietPeriod();
+        List<Future<?>> groupFutures = new ArrayList<>();
+
+        if (tcpBossGroup != null) {
+            LOG.info("Shutting down tcpBossGroup");
+            groupFutures.add(tcpBossGroup.shutdownGracefully(quietPeriod, 10, TimeUnit.SECONDS));
+        }
+
+        if (tcpWorkerGroup != null) {
+            LOG.info("Shutting down tcpWorkerGroup");
+            groupFutures.add(tcpWorkerGroup.shutdownGracefully(quietPeriod, 10, TimeUnit.SECONDS));
+        }
+
+        if (httpBossGroup != null) {
+            LOG.info("Shutting down httpBossGroup");
+            groupFutures.add(httpBossGroup.shutdownGracefully(quietPeriod, 10, TimeUnit.SECONDS));
+        }
+
+        if (httpWorkerGroup != null) {
+            LOG.info("Shutting down httpWorkerGroup");
+            groupFutures.add(httpWorkerGroup.shutdownGracefully(quietPeriod, 10, TimeUnit.SECONDS));
+        }
+
+        if (wsBossGroup != null) {
+            LOG.info("Shutting down wsBossGroup");
+            groupFutures.add(wsBossGroup.shutdownGracefully(quietPeriod, 10, TimeUnit.SECONDS));
+        }
+
+        if (wsWorkerGroup != null) {
+            LOG.info("Shutting down wsWorkerGroup");
+            groupFutures.add(wsWorkerGroup.shutdownGracefully(quietPeriod, 10, TimeUnit.SECONDS));
+        }
+
+        if (udpBossGroup != null) {
+            LOG.info("Shutting down udpBossGroup");
+            groupFutures.add(udpBossGroup.shutdownGracefully(quietPeriod, 10, TimeUnit.SECONDS));
+        }
+
+        if (udpWorkerGroup != null) {
+            LOG.info("Shutting down udpWorkerGroup");
+            groupFutures.add(udpWorkerGroup.shutdownGracefully(quietPeriod, 10, TimeUnit.SECONDS));
+        }
+
+        groupFutures.parallelStream().forEach(f -> {
+            try {
+                f.get();
+            } catch (final Exception e) {
+                LOG.error("Group:" + f.toString() + " -> " + e.getMessage(), e);
+            }
+        });
+
+        try {
+            LOG.info("Closing WebSocketRequestDecoder");
+            WebSocketRequestDecoder.close();
+        } catch (Exception e) {
+            LOG.error("Error closing WebSocketRequestDecoder during shutdown", e);
+        }
+
+        if (this.metricResolver != null) {
+            try {
+                LOG.info("Closing metricResolver");
+                this.metricResolver.stop();
+            } catch (Exception e) {
+                LOG.error(e.getMessage(), e);
+            }
+        }
+
+        if (curatorFramework != null) {
+            try {
+                LOG.info("Closing curatorFramework");
+                curatorFramework.close();
+            } catch (Exception e) {
+                LOG.error(e.getMessage(), e);
+            }
+        }
+
+        if (applicationContext != null) {
+            LOG.info("Closing applicationContext");
+            applicationContext.close();
+        }
+
+        this.shutdown = true;
+        LOG.info("Server shut down.");
+    }
+
+    private static boolean useEpoll() {
+
+        // Should we just return true if this is Linux and if we get an error
+        // during Epoll
+        // setup handle it there?
+        final String os = SystemPropertyUtil.get(OS_NAME).toLowerCase().trim();
+        final String[] version = SystemPropertyUtil.get(OS_VERSION).toLowerCase().trim().split("\\.");
+        if (os.startsWith("linux") && version.length >= 3) {
+            final int major = Integer.parseInt(version[0]);
+            if (major > EPOLL_MIN_MAJOR_VERSION) {
+                return true;
+            } else if (major == EPOLL_MIN_MAJOR_VERSION) {
+                final int minor = Integer.parseInt(version[1]);
+                if (minor > EPOLL_MIN_MINOR_VERSION) {
+                    return true;
+                } else if (minor == EPOLL_MIN_MINOR_VERSION) {
+                    final int patch = Integer.parseInt(version[2].substring(0, 2));
+                    return patch >= EPOLL_MIN_PATCH_VERSION;
+                } else {
+                    return false;
+                }
+            } else {
+                return false;
+            }
+        } else {
+            return false;
+        }
+    }
+
+    protected SslContext createSSLContext(BalancerConfiguration config) throws Exception {
+
+        ServerSsl sslCfg = config.getSecurity().getServerSsl();
+        Boolean generate = sslCfg.isUseGeneratedKeypair();
+        SslContextBuilder ssl;
+        if (generate) {
+            LOG.warn("Using generated self signed server certificate");
+            Date begin = new Date();
+            Date end = new Date(begin.getTime() + 86400000);
+            SelfSignedCertificate ssc = new SelfSignedCertificate("localhost", begin, end);
+            ssl = SslContextBuilder.forServer(ssc.certificate(), ssc.privateKey());
+        } else {
+            String cert = sslCfg.getCertificateFile();
+            String key = sslCfg.getKeyFile();
+            String keyPass = sslCfg.getKeyPassword();
+            if (null == cert || null == key) {
+                throw new IllegalArgumentException("Check your SSL properties, something is wrong.");
+            }
+            ssl = SslContextBuilder.forServer(new File(cert), new File(key), keyPass);
+        }
+
+        ssl.ciphers(sslCfg.getUseCiphers());
+
+        // Can't set to REQUIRE because the CORS pre-flight requests will fail.
+        ssl.clientAuth(ClientAuth.OPTIONAL);
+
+        Boolean useOpenSSL = sslCfg.isUseOpenssl();
+        if (useOpenSSL) {
+            ssl.sslProvider(SslProvider.OPENSSL);
+        } else {
+            ssl.sslProvider(SslProvider.JDK);
+        }
+        String trustStore = sslCfg.getTrustStoreFile();
+        if (null != trustStore) {
+            if (!trustStore.isEmpty()) {
+                ssl.trustManager(new File(trustStore));
+            }
+        }
+        return ssl.build();
+    }
+
+    protected SSLContext createSSLClientContext(BalancerConfiguration config) throws Exception {
+
+        ClientSsl ssl = config.getSecurity().getClientSsl();
+        return HttpClient.getSSLContext(ssl.getTrustStoreFile(), ssl.getTrustStoreType(), ssl.getTrustStorePassword(),
+                ssl.getKeyFile(), ssl.getKeyType(), ssl.getKeyPassword());
+    }
+
+    private void ensureZkPaths(CuratorFramework curatorFramework, String[] paths) {
+        for (String s : paths) {
+            try {
+                Stat stat = curatorFramework.checkExists().forPath(s);
+                if (stat == null) {
+                    curatorFramework.create().creatingParentContainersIfNeeded().withMode(CreateMode.PERSISTENT)
+                            .forPath(s);
+                }
+            } catch (Exception e) {
+                LOG.info(e.getMessage());
+            }
+
+        }
+    }
+
+    public void run() throws Exception {
+
+        // start curator framework
+        RetryPolicy retryPolicy = new RetryForever(1000);
+        int timeout = Long.valueOf(AccumuloConfiguration.getTimeInMillis(balancerConfig.getZooKeeper().getTimeout()))
+                .intValue();
+        curatorFramework = CuratorFrameworkFactory.newClient(balancerConfig.getZooKeeper().getServers(), timeout, 10000,
+                retryPolicy);
+        curatorFramework.start();
+        ensureZkPaths(curatorFramework, zkPaths);
+
+        AuthCache.configure(balancerConfig.getSecurity());
+        final boolean useEpoll = useEpoll();
+        Class<? extends ServerSocketChannel> channelClass;
+        Class<? extends Channel> datagramChannelClass;
+        if (useEpoll) {
+            tcpWorkerGroup = new EpollEventLoopGroup();
+            tcpBossGroup = new EpollEventLoopGroup();
+            httpWorkerGroup = new EpollEventLoopGroup();
+            httpBossGroup = new EpollEventLoopGroup();
+            wsWorkerGroup = new EpollEventLoopGroup();
+            wsBossGroup = new EpollEventLoopGroup();
+            udpWorkerGroup = new EpollEventLoopGroup();
+            udpBossGroup = new EpollEventLoopGroup();
+            channelClass = EpollServerSocketChannel.class;
+            datagramChannelClass = EpollDatagramChannel.class;
+        } else {
+            tcpWorkerGroup = new NioEventLoopGroup();
+            tcpBossGroup = new NioEventLoopGroup();
+            httpWorkerGroup = new NioEventLoopGroup();
+            httpBossGroup = new NioEventLoopGroup();
+            wsWorkerGroup = new NioEventLoopGroup();
+            wsBossGroup = new NioEventLoopGroup();
+            udpWorkerGroup = new NioEventLoopGroup();
+            udpBossGroup = new NioEventLoopGroup();
+            channelClass = NioServerSocketChannel.class;
+            datagramChannelClass = NioDatagramChannel.class;
+        }
+        LOG.info("Using channel class {}", channelClass.getSimpleName());
+
+        List<TcpClientPool> tcpClientPools = new ArrayList<>();
+        for (int x = 0; x < balancerConfig.getServer().getNumTcpPools(); x++) {
+            tcpClientPools.add(new TcpClientPool(this.balancerConfig));
+        }
+        TcpHealthChecker healthChecker = new TcpHealthChecker(this.balancerConfig, tcpClientPools.get(0));
+        this.metricResolver = new BalancedMetricResolver(curatorFramework, this.balancerConfig, healthChecker);
+        this.metricResolver.start();
+
+        final ServerBootstrap tcpServer = new ServerBootstrap();
+        tcpServer.group(tcpBossGroup, tcpWorkerGroup);
+        tcpServer.channel(channelClass);
+        tcpServer.handler(new LoggingHandler());
+        tcpServer.childHandler(setupTcpChannel(metricResolver, tcpClientPools));
+        tcpServer.option(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT);
+        tcpServer.option(ChannelOption.SO_BACKLOG, 128);
+        tcpServer.option(ChannelOption.SO_KEEPALIVE, true);
+        final int tcpPort = balancerConfig.getServer().getTcpPort();
+        final String tcpIp = balancerConfig.getServer().getIp();
+        tcpChannelHandle = tcpServer.bind(tcpIp, tcpPort).sync().channel();
+        final String tcpAddress = ((InetSocketAddress) tcpChannelHandle.localAddress()).getAddress().getHostAddress();
+
+        final int httpPort = balancerConfig.getHttp().getPort();
+        final String httpIp = balancerConfig.getHttp().getIp();
+        SslContext sslCtx = createSSLContext(balancerConfig);
+        if (sslCtx instanceof OpenSslServerContext) {
+            OpenSslServerContext openssl = (OpenSslServerContext) sslCtx;
+            String application = "Timely_" + httpPort;
+            OpenSslServerSessionContext opensslCtx = openssl.sessionContext();
+            opensslCtx.setSessionCacheEnabled(true);
+            opensslCtx.setSessionCacheSize(128);
+            opensslCtx.setSessionIdContext(application.getBytes(StandardCharsets.UTF_8));
+            opensslCtx.setSessionTimeout(balancerConfig.getSecurity().getSessionMaxAge());
+        }
+        SSLContext clientSSLContext = createSSLClientContext(balancerConfig);
+        final ServerBootstrap httpServer = new ServerBootstrap();
+        httpServer.group(httpBossGroup, httpWorkerGroup);
+        httpServer.channel(channelClass);
+        httpServer.handler(new LoggingHandler());
+        HttpClientPool httpClientPool = new HttpClientPool(balancerConfig.getSecurity(), balancerConfig.getHttp(),
+                clientSSLContext);
+        httpServer.childHandler(setupHttpChannel(balancerConfig, sslCtx, metricResolver, httpClientPool));
+        httpServer.option(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT);
+        httpServer.option(ChannelOption.SO_BACKLOG, 128);
+        httpServer.option(ChannelOption.SO_KEEPALIVE, true);
+        httpChannelHandle = httpServer.bind(httpIp, httpPort).sync().channel();
+        final String httpAddress = ((InetSocketAddress) httpChannelHandle.localAddress()).getAddress().getHostAddress();
+
+        final int wsPort = balancerConfig.getWebsocket().getPort();
+        final String wsIp = balancerConfig.getWebsocket().getIp();
+        final ServerBootstrap wsServer = new ServerBootstrap();
+        wsServer.group(wsBossGroup, wsWorkerGroup);
+        wsServer.channel(channelClass);
+        wsServer.handler(new LoggingHandler());
+        WsClientPool wsClientPool = new WsClientPool(balancerConfig, clientSSLContext);
+        wsServer.childHandler(setupWSChannel(balancerConfig, sslCtx, metricResolver, wsClientPool));
+        wsServer.option(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT);
+        wsServer.option(ChannelOption.SO_BACKLOG, 128);
+        wsServer.option(ChannelOption.SO_KEEPALIVE, true);
+        /* Not sure if next two lines are necessary */
+        wsServer.option(ChannelOption.SO_SNDBUF, 1048576);
+        wsServer.option(ChannelOption.WRITE_BUFFER_WATER_MARK, new WriteBufferWaterMark(620145, 838860));
+        wsChannelHandle = wsServer.bind(wsIp, wsPort).sync().channel();
+        final String wsAddress = ((InetSocketAddress) wsChannelHandle.localAddress()).getAddress().getHostAddress();
+
+        final int udpPort = balancerConfig.getServer().getUdpPort();
+        final String udpIp = balancerConfig.getServer().getIp();
+        UdpClientPool udpClientPool = new UdpClientPool(balancerConfig);
+        for (int n = 1; n < DEFAULT_EVENT_LOOP_THREADS; n++) {
+            final Bootstrap udpServer = new Bootstrap();
+            udpServer.group(udpBossGroup);
+            udpServer.channel(datagramChannelClass);
+            udpServer.handler(setupUdpChannel(metricResolver, udpClientPool));
+            udpServer.option(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT);
+            udpServer.option(EpollChannelOption.SO_REUSEADDR, true);
+            udpServer.option(EpollChannelOption.SO_REUSEPORT, true);
+            udpChannelHandleList.add(udpServer.bind(udpIp, udpPort).sync().channel());
+        }
+        shutdownHook();
+        LOG.info(
+                "Server started. Listening on {}:{} for TCP traffic, {}:{} for HTTP traffic, {}:{} for WebSocket traffic, and {}:{} for UDP traffic",
+                tcpAddress, tcpPort, httpAddress, httpPort, wsAddress, wsPort, wsAddress, udpPort);
+    }
+
+    public static void main(String[] args) throws Exception {
+
+        Balancer.applicationContext = Balancer.initializeContext(args);
+        BalancerConfiguration balancerConf = Balancer.applicationContext.getBean(BalancerConfiguration.class);
+
+        Balancer balancer = new Balancer(balancerConf);
+        try {
+            balancer.run();
+            LATCH.await();
+        } catch (final InterruptedException e) {
+            LOG.info("Server shutting down.");
+        } catch (Exception e) {
+            LOG.error("Error running server.", e);
+        } finally {
+            try {
+                balancer.shutdown();
+            } catch (Exception e) {
+                System.exit(1);
+            }
+        }
+    }
+
+    protected ChannelHandler setupHttpChannel(BalancerConfiguration balancerConfig, SslContext sslCtx,
+            MetricResolver metricResolver, HttpClientPool httpClientPool) {
+
+        return new ChannelInitializer<SocketChannel>() {
+
+            @Override
+            protected void initChannel(SocketChannel ch) throws Exception {
+
+                ch.pipeline().addLast("ssl", new NonSslRedirectHandler(balancerConfig.getHttp(), sslCtx));
+                ch.pipeline().addLast("encoder", new HttpResponseEncoder());
+                ch.pipeline().addLast("decoder", new HttpRequestDecoder());
+                ch.pipeline().addLast("compressor", new HttpContentCompressor());
+                ch.pipeline().addLast("decompressor", new HttpContentDecompressor());
+                ch.pipeline().addLast("aggregator", new HttpObjectAggregator(65536));
+                ch.pipeline().addLast("chunker", new ChunkedWriteHandler());
+                ch.pipeline().addLast("queryDecoder", new timely.netty.http.HttpRequestDecoder(
+                        balancerConfig.getSecurity(), balancerConfig.getHttp()));
+                ch.pipeline().addLast("fileServer", new HttpStaticFileServerHandler().setIgnoreSslHandshakeErrors(
+                        balancerConfig.getSecurity().getServerSsl().isUseGeneratedKeypair()));
+                ch.pipeline().addLast("login",
+                        new X509LoginRequestHandler(balancerConfig.getSecurity(), balancerConfig.getHttp()));
+                ch.pipeline().addLast("httpRelay", new HttpRelayHandler(metricResolver, httpClientPool));
+                ch.pipeline().addLast("error", new TimelyExceptionHandler().setIgnoreSslHandshakeErrors(
+                        balancerConfig.getSecurity().getServerSsl().isUseGeneratedKeypair()));
+            }
+        };
+    }
+
+    protected ChannelHandler setupUdpChannel(MetricResolver metricResolver, UdpClientPool udpClientPool) {
+        return new ChannelInitializer<DatagramChannel>() {
+
+            @Override
+            protected void initChannel(DatagramChannel ch) throws Exception {
+                ch.pipeline().addLast("logger", new LoggingHandler());
+                ch.pipeline().addLast("packetDecoder", new UdpPacketToByteBuf());
+                ch.pipeline().addLast("buffer", new MetricsBufferDecoder());
+                ch.pipeline().addLast("frame", new DelimiterBasedFrameDecoder(65536, true, Delimiters.lineDelimiter()));
+                ch.pipeline().addLast("putDecoder", new UdpDecoder());
+                ch.pipeline().addLast("udpRelayHandler", new UdpRelayHandler(metricResolver, udpClientPool));
+            }
+        };
+    }
+
+    protected ChannelHandler setupTcpChannel(MetricResolver metricResolver, List<TcpClientPool> tcpClientPools) {
+        return new ChannelInitializer<SocketChannel>() {
+
+            @Override
+            protected void initChannel(SocketChannel ch) throws Exception {
+                ch.pipeline().addLast("buffer", new MetricsBufferDecoder());
+                ch.pipeline().addLast("frame", new DelimiterBasedFrameDecoder(65536, true, Delimiters.lineDelimiter()));
+                ch.pipeline().addLast("putDecoder", new TcpDecoder());
+                ch.pipeline().addLast("tcpRelayHandler", new TcpRelayHandler(metricResolver, tcpClientPools));
+                ch.pipeline().addLast("versionHandler", new TcpVersionHandler());
+            }
+        };
+    }
+
+    protected ChannelHandler setupWSChannel(BalancerConfiguration balancerConfig, SslContext sslCtx,
+            MetricResolver metricResolver, WsClientPool wsClientPool) {
+        return new ChannelInitializer<SocketChannel>() {
+
+            @Override
+            protected void initChannel(SocketChannel ch) throws Exception {
+                ch.pipeline().addLast("ssl", sslCtx.newHandler(ch.alloc()));
+                ch.pipeline().addLast("httpServer", new HttpServerCodec());
+                ch.pipeline().addLast("aggregator", new HttpObjectAggregator(65536));
+                ch.pipeline().addLast("sessionExtractor", new WebSocketFullRequestHandler());
+
+                ch.pipeline().addLast("idle-handler",
+                        new IdleStateHandler(balancerConfig.getWebsocket().getTimeout(), 0, 0));
+                ch.pipeline().addLast("ws-protocol",
+                        new WebSocketServerProtocolHandler(WS_PATH, null, true, 65536, false, true));
+                ch.pipeline().addLast("wsDecoder", new WebSocketRequestDecoder(balancerConfig.getSecurity()));
+                ch.pipeline().addLast("httpRelay", new WsRelayHandler(balancerConfig, metricResolver, wsClientPool));
+                ch.pipeline().addLast("error", new WSTimelyExceptionHandler());
+            }
+        };
+    }
+}

balancer/src/main/java/timely/balancer/configuration/BalancerConfiguration.java

@@ -0,0 +1,173 @@
+package timely.balancer.configuration;
+
+import javax.validation.Valid;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+import org.springframework.stereotype.Component;
+import org.springframework.validation.annotation.Validated;
+import timely.configuration.Cache;
+
+@Validated
+@Component
+@ConfigurationProperties(prefix = "timely-balancer")
+public class BalancerConfiguration {
+
+    @Valid
+    @NestedConfigurationProperty
+    private BalancerServer server = new BalancerServer();
+
+    @Valid
+    @NestedConfigurationProperty
+    private BalancerHttp http = new BalancerHttp();
+
+    @Valid
+    @NestedConfigurationProperty
+    private BalancerWebsocket websocket = new BalancerWebsocket();
+
+    @Valid
+    @NestedConfigurationProperty
+    private ZooKeeper zooKeeper = new ZooKeeper();
+
+    @Valid
+    @NestedConfigurationProperty
+    private BalancerSecurity security = new BalancerSecurity();
+
+    @Valid
+    @NestedConfigurationProperty
+    private Cache cache = new Cache();
+
+    private boolean loginRequired = false;
+
+    private String assignmentFile;
+
+    private Double controlBandPercentage = 0.05;
+
+    private long checkServerHealthInterval = 10000;
+
+    private int serverFailuresBeforeDown = 3;
+
+    private int serverSuccessesBeforeUp = 3;
+
+    private String metricAssignmentPersisterType = "HDFS";
+
+    private long balanceDelay = 900000;
+
+    private long balancePeriod = 900000;
+
+    private long persistDelay = 10000;
+
+    private long persistPeriod = 60000;
+
+    public ZooKeeper getZooKeeper() {
+        return zooKeeper;
+    }
+
+    public void setLoginRequired(boolean loginRequired) {
+        this.loginRequired = loginRequired;
+    }
+
+    public boolean isLoginRequired() {
+        return loginRequired;
+    }
+
+    public String getAssignmentFile() {
+        return assignmentFile;
+    }
+
+    public void setAssignmentFile(String assignmentFile) {
+        this.assignmentFile = assignmentFile;
+    }
+
+    public void setControlBandPercentage(Double controlBandPercentage) {
+        this.controlBandPercentage = controlBandPercentage;
+    }
+
+    public Double getControlBandPercentage() {
+        return controlBandPercentage;
+    }
+
+    public BalancerSecurity getSecurity() {
+        return security;
+    }
+
+    public BalancerServer getServer() {
+        return server;
+    }
+
+    public BalancerHttp getHttp() {
+        return http;
+    }
+
+    public BalancerWebsocket getWebsocket() {
+        return websocket;
+    }
+
+    public Cache getCache() {
+        return cache;
+    }
+
+    public void setCheckServerHealthInterval(long checkServerHealthInterval) {
+        this.checkServerHealthInterval = checkServerHealthInterval;
+    }
+
+    public long getCheckServerHealthInterval() {
+        return checkServerHealthInterval;
+    }
+
+    public int getServerFailuresBeforeDown() {
+        return serverFailuresBeforeDown;
+    }
+
+    public void setServerFailuresBeforeDown(int serverFailuresBeforeDown) {
+        this.serverFailuresBeforeDown = serverFailuresBeforeDown;
+    }
+
+    public int getServerSuccessesBeforeUp() {
+        return serverSuccessesBeforeUp;
+    }
+
+    public void setServerSuccessesBeforeUp(int serverSuccessesBeforeUp) {
+        this.serverSuccessesBeforeUp = serverSuccessesBeforeUp;
+    }
+
+    public String getMetricAssignmentPersisterType() {
+        return metricAssignmentPersisterType;
+    }
+
+    public void setMetricAssignmentPersisterType(String metricAssignmentPersisterType) {
+        this.metricAssignmentPersisterType = metricAssignmentPersisterType;
+    }
+
+    public void setBalanceDelay(long balanceDelay) {
+        this.balanceDelay = balanceDelay;
+    }
+
+    public long getBalanceDelay() {
+        return balanceDelay;
+    }
+
+    public void setBalancePeriod(long balancePeriod) {
+        this.balancePeriod = balancePeriod;
+    }
+
+    public long getBalancePeriod() {
+        return balancePeriod;
+    }
+
+    public void setPersistDelay(long persistDelay) {
+        this.persistDelay = persistDelay;
+    }
+
+    public long getPersistDelay() {
+        return persistDelay;
+    }
+
+    public void setPersistPeriod(long persistPeriod) {
+        this.persistPeriod = persistPeriod;
+    }
+
+    public long getPersistPeriod() {
+        return persistPeriod;
+    }
+}

balancer/src/main/java/timely/balancer/configuration/BalancerHttp.java

@@ -0,0 +1,19 @@
+package timely.balancer.configuration;
+
+import javax.validation.Valid;
+
+import org.apache.commons.pool2.impl.GenericKeyedObjectPoolConfig;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+import timely.configuration.Http;
+
+public class BalancerHttp extends Http {
+
+    @Valid
+    @NestedConfigurationProperty
+    private GenericKeyedObjectPoolConfig<CloseableHttpClient> httpClientPool = new GenericKeyedObjectPoolConfig<>();
+
+    public GenericKeyedObjectPoolConfig<CloseableHttpClient> getHttpClientPool() {
+        return httpClientPool;
+    }
+}

balancer/src/main/java/timely/balancer/configuration/BalancerSecurity.java

@@ -0,0 +1,17 @@
+package timely.balancer.configuration;
+
+import javax.validation.Valid;
+
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+import timely.configuration.Security;
+
+public class BalancerSecurity extends Security {
+
+    @Valid
+    @NestedConfigurationProperty
+    private ClientSsl clientSsl = new ClientSsl();
+
+    public ClientSsl getClientSsl() {
+        return clientSsl;
+    }
+}

balancer/src/main/java/timely/balancer/configuration/BalancerServer.java

@@ -0,0 +1,48 @@
+package timely.balancer.configuration;
+
+import javax.validation.Valid;
+
+import org.apache.commons.pool2.impl.GenericKeyedObjectPoolConfig;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+import timely.client.tcp.TcpClient;
+import timely.client.udp.UdpClient;
+import timely.configuration.Server;
+
+public class BalancerServer extends Server {
+
+    @Valid
+    @NestedConfigurationProperty
+    private GenericKeyedObjectPoolConfig<UdpClient> udpClientPool = new GenericKeyedObjectPoolConfig<>();
+
+    @Valid
+    @NestedConfigurationProperty
+    private GenericKeyedObjectPoolConfig<TcpClient> tcpClientPool = new GenericKeyedObjectPoolConfig<>();
+
+    private int numTcpPools = 1;
+
+    private int tcpBufferSize = -1;
+
+    public GenericKeyedObjectPoolConfig<UdpClient> getUdpClientPool() {
+        return udpClientPool;
+    }
+
+    public GenericKeyedObjectPoolConfig<TcpClient> getTcpClientPool() {
+        return tcpClientPool;
+    }
+
+    public int getNumTcpPools() {
+        return numTcpPools;
+    }
+
+    public void setNumTcpPools(int numTcpPools) {
+        this.numTcpPools = numTcpPools;
+    }
+
+    public int getTcpBufferSize() {
+        return tcpBufferSize;
+    }
+
+    public void setTcpBufferSize(int tcpBufferSize) {
+        this.tcpBufferSize = tcpBufferSize;
+    }
+}

balancer/src/main/java/timely/balancer/configuration/BalancerWebsocket.java

@@ -0,0 +1,29 @@
+package timely.balancer.configuration;
+
+import javax.validation.Valid;
+
+import org.apache.commons.pool2.impl.GenericKeyedObjectPoolConfig;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+import timely.client.websocket.subscription.WebSocketSubscriptionClient;
+import timely.configuration.Websocket;
+
+public class BalancerWebsocket extends Websocket {
+
+    @Valid
+    @NestedConfigurationProperty
+    private GenericKeyedObjectPoolConfig<WebSocketSubscriptionClient> wsClientPool = new GenericKeyedObjectPoolConfig<>();
+
+    public GenericKeyedObjectPoolConfig<WebSocketSubscriptionClient> getWsClientPool() {
+        return wsClientPool;
+    }
+
+    public int incomingBufferSize = 50000000;
+
+    public int getIncomingBufferSize() {
+        return incomingBufferSize;
+    }
+
+    public void setIncomingBufferSize(int incomingBufferSize) {
+        this.incomingBufferSize = incomingBufferSize;
+    }
+}

balancer/src/main/java/timely/balancer/configuration/ClientSsl.java

@@ -0,0 +1,77 @@
+package timely.balancer.configuration;
+
+public class ClientSsl {
+
+    private String keyFile;
+    private String keyType;
+    private String keyPassword;
+    private String trustStoreFile;
+    private String trustStoreType;
+    private String trustStorePassword;
+    private boolean useClientCert = true;
+    private boolean hostVerificationEnabled = true;
+
+    public String getKeyFile() {
+        return keyFile;
+    }
+
+    public void setKeyFile(String keyFile) {
+        this.keyFile = keyFile;
+    }
+
+    public String getKeyType() {
+        return keyType;
+    }
+
+    public void setKeyType(String keyType) {
+        this.keyType = keyType;
+    }
+
+    public String getKeyPassword() {
+        return keyPassword;
+    }
+
+    public void setKeyPassword(String keyPassword) {
+        this.keyPassword = keyPassword;
+    }
+
+    public String getTrustStoreFile() {
+        return trustStoreFile;
+    }
+
+    public void setTrustStoreFile(String trustStoreFile) {
+        this.trustStoreFile = trustStoreFile;
+    }
+
+    public String getTrustStoreType() {
+        return trustStoreType;
+    }
+
+    public void setTrustStoreType(String trustStoreType) {
+        this.trustStoreType = trustStoreType;
+    }
+
+    public String getTrustStorePassword() {
+        return trustStorePassword;
+    }
+
+    public void setTrustStorePassword(String trustStorePassword) {
+        this.trustStorePassword = trustStorePassword;
+    }
+
+    public void setUseClientCert(boolean useClientCert) {
+        this.useClientCert = useClientCert;
+    }
+
+    public boolean isUseClientCert() {
+        return useClientCert;
+    }
+
+    public void setHostVerificationEnabled(boolean hostVerificationEnabled) {
+        this.hostVerificationEnabled = hostVerificationEnabled;
+    }
+
+    public boolean isHostVerificationEnabled() {
+        return hostVerificationEnabled;
+    }
+}

balancer/src/main/java/timely/balancer/configuration/SpringBootstrap.java

@@ -0,0 +1,7 @@
+package timely.balancer.configuration;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication(scanBasePackageClasses = { SpringBootstrap.class })
+public class SpringBootstrap {
+}

balancer/src/main/java/timely/balancer/configuration/ZooKeeper.java

@@ -0,0 +1,27 @@
+package timely.balancer.configuration;
+
+import javax.validation.constraints.NotBlank;
+
+public class ZooKeeper {
+
+    private String servers;
+
+    @NotBlank
+    private String timeout = "120s";
+
+    public String getServers() {
+        return servers;
+    }
+
+    public void setServers(String servers) {
+        this.servers = servers;
+    }
+
+    public String getTimeout() {
+        return timeout;
+    }
+
+    public void setTimeout(String timeout) {
+        this.timeout = timeout;
+    }
+}

balancer/src/main/java/timely/balancer/connection/TimelyBalancedHost.java

@@ -0,0 +1,194 @@
+package timely.balancer.connection;
+
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import org.apache.commons.lang3.builder.HashCodeBuilder;
+import org.apache.commons.lang3.builder.ToStringBuilder;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.balancer.ArrivalRate;
+import timely.balancer.configuration.BalancerConfiguration;
+
+public class TimelyBalancedHost {
+
+    private static final Logger LOG = LoggerFactory.getLogger(TimelyBalancedHost.class);
+
+    private String host;
+    private int tcpPort;
+    private int httpPort;
+    private int wsPort;
+    private int udpPort;
+    private boolean isUp = true;
+    private BalancerConfiguration balancerConfig;
+    private int failures = 0;
+    private int successes = 0;
+    private ArrivalRate arrivalRate = null;
+
+    private TimelyBalancedHost() {
+
+    }
+
+    private TimelyBalancedHost(String host, int tcpPort, int httpPort, int wsPort, int udpPort,
+            ArrivalRate arrivalRate) {
+        this.host = host;
+        this.tcpPort = tcpPort;
+        this.httpPort = httpPort;
+        this.wsPort = wsPort;
+        this.udpPort = udpPort;
+        this.arrivalRate = arrivalRate;
+    }
+
+    static public TimelyBalancedHost of(String host, int tcpPort, int httpPort, int wsPort, int udpPort,
+            ArrivalRate arrivalRate) {
+        return new TimelyBalancedHost(host, tcpPort, httpPort, wsPort, udpPort, arrivalRate);
+    }
+
+    static public TimelyBalancedHost of(String host, int basePort) {
+        return new TimelyBalancedHost(host, basePort, basePort + 1, basePort + 2, basePort + 3, null);
+    }
+
+    public void setBalancerConfig(BalancerConfiguration balancerConfig) {
+        this.balancerConfig = balancerConfig;
+    }
+
+    synchronized public boolean isUp() {
+        return isUp;
+    }
+
+    public void reportSuccess() {
+        int serverSuccessesBeforeUp = balancerConfig.getServerSuccessesBeforeUp();
+        String h = host;
+        int p = tcpPort;
+        synchronized (this) {
+            if (LOG.isTraceEnabled()) {
+                LOG.trace("success reported host:{} port:{} isUp:{} successes:{} serverSuccessesBeforeUp:{}", h, p,
+                        isUp, (successes + 1), serverSuccessesBeforeUp);
+            }
+            if (!isUp) {
+                if (++successes >= serverSuccessesBeforeUp) {
+                    isUp = true;
+                    successes = 0;
+                    LOG.info("host up host:{} port:{}", h, p);
+                }
+            }
+        }
+    }
+
+    public void reportFailure() {
+        int serverFailuresBeforeDown = balancerConfig.getServerFailuresBeforeDown();
+        String h = host;
+        int p = tcpPort;
+        synchronized (this) {
+            if (LOG.isTraceEnabled()) {
+                LOG.trace("failure reported host:{} port:{} isUp:{} failures:{} serverFailuresBeforeUp:{}", h, p, isUp,
+                        (failures + 1), serverFailuresBeforeDown);
+            }
+            if (isUp) {
+                if (++failures >= serverFailuresBeforeDown) {
+                    isUp = false;
+                    failures = 0;
+                    LOG.info("host down host:{} port:{}", h, p);
+                }
+            }
+        }
+    }
+
+    public String getHost() {
+        return host;
+    }
+
+    public void setHost(String host) {
+        this.host = host;
+    }
+
+    public int getUdpPort() {
+        return udpPort;
+    }
+
+    public void setUdpPort(int udpPort) {
+        this.udpPort = udpPort;
+    }
+
+    public int getTcpPort() {
+        return tcpPort;
+    }
+
+    public void setTcpPort(int tcpPort) {
+        this.tcpPort = tcpPort;
+    }
+
+    public int getHttpPort() {
+        return httpPort;
+    }
+
+    public void setHttpPort(int httpPort) {
+        this.httpPort = httpPort;
+    }
+
+    public int getWsPort() {
+        return wsPort;
+    }
+
+    public void setWsPort(int wsPort) {
+        this.wsPort = wsPort;
+    }
+
+    public void arrived() {
+        if (this.arrivalRate != null) {
+            this.arrivalRate.arrived();
+        }
+    }
+
+    public double getArrivalRate() {
+        if (this.arrivalRate == null) {
+            return 0;
+        } else {
+            return this.arrivalRate.getRate();
+        }
+    }
+
+    @Override
+    public int hashCode() {
+        HashCodeBuilder builder = new HashCodeBuilder();
+        builder.append(host);
+        builder.append(tcpPort);
+        builder.append(httpPort);
+        builder.append(wsPort);
+        builder.append(udpPort);
+        return builder.toHashCode();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (o instanceof TimelyBalancedHost) {
+            TimelyBalancedHost other = (TimelyBalancedHost) o;
+            EqualsBuilder builder = new EqualsBuilder();
+            builder.append(host, other.host);
+            builder.append(tcpPort, other.tcpPort);
+            builder.append(httpPort, other.httpPort);
+            builder.append(wsPort, other.wsPort);
+            builder.append(udpPort, other.udpPort);
+            return builder.isEquals();
+        } else {
+            return false;
+        }
+    }
+
+    @Override
+    public String toString() {
+        ToStringBuilder builder = new ToStringBuilder(this);
+        builder.append(host);
+        builder.append(tcpPort);
+        builder.append(httpPort);
+        builder.append(wsPort);
+        builder.append(udpPort);
+        builder.append(isUp);
+        return builder.toString();
+    }
+
+    public static String toStringShort(TimelyBalancedHost tbh) {
+        if (tbh == null) {
+            return null;
+        }
+        return tbh.host + ":" + tbh.tcpPort;
+    }
+}

balancer/src/main/java/timely/balancer/connection/http/HttpClientFactory.java

@@ -0,0 +1,48 @@
+package timely.balancer.connection.http;
+
+import javax.net.ssl.SSLContext;
+
+import org.apache.commons.pool2.KeyedPooledObjectFactory;
+import org.apache.commons.pool2.PooledObject;
+import org.apache.commons.pool2.impl.DefaultPooledObject;
+import org.apache.http.impl.client.CloseableHttpClient;
+import timely.balancer.configuration.BalancerSecurity;
+import timely.balancer.connection.TimelyBalancedHost;
+
+public class HttpClientFactory implements KeyedPooledObjectFactory<TimelyBalancedHost, CloseableHttpClient> {
+
+    private final SSLContext sslContext;
+    private final BalancerSecurity security;
+
+    public HttpClientFactory(BalancerSecurity security, SSLContext sslContext) {
+        this.security = security;
+        this.sslContext = sslContext;
+    }
+
+    @Override
+    public PooledObject<CloseableHttpClient> makeObject(TimelyBalancedHost k) throws Exception {
+        // disable cookie management because we are sharing connections
+        return new DefaultPooledObject<>(timely.client.http.HttpClient.get(this.sslContext, null,
+                security.getClientSsl().isHostVerificationEnabled(), security.getClientSsl().isUseClientCert()));
+    }
+
+    @Override
+    public void destroyObject(TimelyBalancedHost k, PooledObject<CloseableHttpClient> o) throws Exception {
+
+    }
+
+    @Override
+    public boolean validateObject(TimelyBalancedHost k, PooledObject<CloseableHttpClient> o) {
+        return true;
+    }
+
+    @Override
+    public void activateObject(TimelyBalancedHost k, PooledObject<CloseableHttpClient> o) throws Exception {
+
+    }
+
+    @Override
+    public void passivateObject(TimelyBalancedHost k, PooledObject<CloseableHttpClient> o) throws Exception {
+
+    }
+}

balancer/src/main/java/timely/balancer/connection/http/HttpClientPool.java

@@ -0,0 +1,16 @@
+package timely.balancer.connection.http;
+
+import javax.net.ssl.SSLContext;
+
+import org.apache.commons.pool2.impl.GenericKeyedObjectPool;
+import org.apache.http.impl.client.CloseableHttpClient;
+import timely.balancer.configuration.BalancerHttp;
+import timely.balancer.configuration.BalancerSecurity;
+import timely.balancer.connection.TimelyBalancedHost;
+
+public class HttpClientPool extends GenericKeyedObjectPool<TimelyBalancedHost, CloseableHttpClient> {
+
+    public HttpClientPool(BalancerSecurity balancerSecurity, BalancerHttp http, SSLContext sslContext) {
+        super(new HttpClientFactory(balancerSecurity, sslContext), http.getHttpClientPool());
+    }
+}

balancer/src/main/java/timely/balancer/connection/tcp/TcpClientFactory.java

@@ -0,0 +1,56 @@
+package timely.balancer.connection.tcp;
+
+import java.io.IOException;
+
+import org.apache.commons.pool2.KeyedPooledObjectFactory;
+import org.apache.commons.pool2.PooledObject;
+import org.apache.commons.pool2.impl.DefaultPooledObject;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.client.tcp.TcpClient;
+
+public class TcpClientFactory implements KeyedPooledObjectFactory<TimelyBalancedHost, TcpClient> {
+
+    private int bufferSize;
+
+    public TcpClientFactory(int bufferSize) {
+        this.bufferSize = bufferSize;
+    }
+
+    @Override
+    public PooledObject<TcpClient> makeObject(TimelyBalancedHost k) throws Exception {
+        return new DefaultPooledObject<>(new TcpClient(k.getHost(), k.getTcpPort(), bufferSize));
+    }
+
+    @Override
+    public void destroyObject(TimelyBalancedHost k, PooledObject<TcpClient> o) throws Exception {
+        try {
+            o.getObject().flush();
+            o.getObject().close();
+        } catch (IOException e) {
+            throw new IOException("Error closing connection to " + k.getHost() + ":" + k.getTcpPort());
+        }
+    }
+
+    @Override
+    public boolean validateObject(TimelyBalancedHost k, PooledObject<TcpClient> o) {
+        return true;
+    }
+
+    @Override
+    public void activateObject(TimelyBalancedHost k, PooledObject<TcpClient> o) throws Exception {
+        try {
+            o.getObject().open();
+        } catch (Exception e) {
+            throw new IOException("Unable to connect to " + k.getHost() + ":" + k.getTcpPort(), e);
+        }
+    }
+
+    @Override
+    public void passivateObject(TimelyBalancedHost k, PooledObject<TcpClient> o) throws Exception {
+        try {
+            o.getObject().flush();
+        } catch (Exception e) {
+            throw new IOException("Error flushing connection to " + k.getHost() + ":" + k.getTcpPort());
+        }
+    }
+}

balancer/src/main/java/timely/balancer/connection/tcp/TcpClientPool.java

@@ -0,0 +1,13 @@
+package timely.balancer.connection.tcp;
+
+import org.apache.commons.pool2.impl.GenericKeyedObjectPool;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.client.tcp.TcpClient;
+
+public class TcpClientPool extends GenericKeyedObjectPool<TimelyBalancedHost, TcpClient> {
+
+    public TcpClientPool(BalancerConfiguration config) {
+        super(new TcpClientFactory(config.getServer().getTcpBufferSize()), config.getServer().getTcpClientPool());
+    }
+}

balancer/src/main/java/timely/balancer/connection/udp/UdpClientFactory.java

@@ -0,0 +1,53 @@
+package timely.balancer.connection.udp;
+
+import java.io.IOException;
+
+import org.apache.commons.pool2.KeyedPooledObjectFactory;
+import org.apache.commons.pool2.PooledObject;
+import org.apache.commons.pool2.impl.DefaultPooledObject;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.client.udp.UdpClient;
+
+public class UdpClientFactory implements KeyedPooledObjectFactory<TimelyBalancedHost, UdpClient> {
+
+    public UdpClientFactory() {
+    }
+
+    @Override
+    public PooledObject<UdpClient> makeObject(TimelyBalancedHost k) throws Exception {
+        return new DefaultPooledObject<>(new UdpClient(k.getHost(), k.getUdpPort()));
+    }
+
+    @Override
+    public void destroyObject(TimelyBalancedHost k, PooledObject<UdpClient> o) throws Exception {
+        try {
+            o.getObject().flush();
+            o.getObject().close();
+        } catch (IOException e) {
+            throw new IOException("Error closing connection to " + k.getHost() + ":" + k.getUdpPort());
+        }
+    }
+
+    @Override
+    public boolean validateObject(TimelyBalancedHost k, PooledObject<UdpClient> o) {
+        return true;
+    }
+
+    @Override
+    public void activateObject(TimelyBalancedHost k, PooledObject<UdpClient> o) throws Exception {
+        try {
+            o.getObject().open();
+        } catch (Exception e) {
+            throw new IOException("Unable to connect to " + k.getHost() + ":" + k.getUdpPort(), e);
+        }
+    }
+
+    @Override
+    public void passivateObject(TimelyBalancedHost k, PooledObject<UdpClient> o) throws Exception {
+        try {
+            o.getObject().flush();
+        } catch (Exception e) {
+            throw new IOException("Error flushing connection to " + k.getHost() + ":" + k.getUdpPort());
+        }
+    }
+}

balancer/src/main/java/timely/balancer/connection/udp/UdpClientPool.java

@@ -0,0 +1,13 @@
+package timely.balancer.connection.udp;
+
+import org.apache.commons.pool2.impl.GenericKeyedObjectPool;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.client.udp.UdpClient;
+
+public class UdpClientPool extends GenericKeyedObjectPool<TimelyBalancedHost, UdpClient> {
+
+    public UdpClientPool(BalancerConfiguration config) {
+        super(new UdpClientFactory(), config.getServer().getUdpClientPool());
+    }
+}

balancer/src/main/java/timely/balancer/connection/ws/WsClientFactory.java

@@ -0,0 +1,52 @@
+package timely.balancer.connection.ws;
+
+import javax.net.ssl.SSLContext;
+
+import org.apache.commons.pool2.KeyedPooledObjectFactory;
+import org.apache.commons.pool2.PooledObject;
+import org.apache.commons.pool2.impl.DefaultPooledObject;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.client.websocket.subscription.WebSocketSubscriptionClient;
+
+public class WsClientFactory implements KeyedPooledObjectFactory<TimelyBalancedHost, WebSocketSubscriptionClient> {
+
+    private final SSLContext sslContext;
+    private BalancerConfiguration balancerConfig;
+
+    public WsClientFactory(BalancerConfiguration balancerConfig, SSLContext sslContext) {
+        this.balancerConfig = balancerConfig;
+        this.sslContext = sslContext;
+    }
+
+    @Override
+    public PooledObject<WebSocketSubscriptionClient> makeObject(TimelyBalancedHost k) throws Exception {
+
+        int bufferSize = balancerConfig.getWebsocket().getIncomingBufferSize();
+        WebSocketSubscriptionClient client = new WebSocketSubscriptionClient(sslContext, k.getHost(), k.getHttpPort(),
+                k.getWsPort(), balancerConfig.getSecurity().getClientSsl().isUseClientCert(),
+                balancerConfig.isLoginRequired(), "", "",
+                balancerConfig.getSecurity().getClientSsl().isHostVerificationEnabled(), bufferSize);
+        return new DefaultPooledObject<>(client);
+    }
+
+    @Override
+    public void destroyObject(TimelyBalancedHost k, PooledObject<WebSocketSubscriptionClient> o) throws Exception {
+
+    }
+
+    @Override
+    public boolean validateObject(TimelyBalancedHost k, PooledObject<WebSocketSubscriptionClient> o) {
+        return true;
+    }
+
+    @Override
+    public void activateObject(TimelyBalancedHost k, PooledObject<WebSocketSubscriptionClient> o) throws Exception {
+
+    }
+
+    @Override
+    public void passivateObject(TimelyBalancedHost k, PooledObject<WebSocketSubscriptionClient> o) throws Exception {
+
+    }
+}

balancer/src/main/java/timely/balancer/connection/ws/WsClientPool.java

@@ -0,0 +1,15 @@
+package timely.balancer.connection.ws;
+
+import javax.net.ssl.SSLContext;
+
+import org.apache.commons.pool2.impl.GenericKeyedObjectPool;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.client.websocket.subscription.WebSocketSubscriptionClient;
+
+public class WsClientPool extends GenericKeyedObjectPool<TimelyBalancedHost, WebSocketSubscriptionClient> {
+
+    public WsClientPool(BalancerConfiguration balancerConfig, SSLContext sslContext) {
+        super(new WsClientFactory(balancerConfig, sslContext), balancerConfig.getWebsocket().getWsClientPool());
+    }
+}

balancer/src/main/java/timely/balancer/healthcheck/HealthChecker.java

@@ -0,0 +1,12 @@
+package timely.balancer.healthcheck;
+
+import java.util.List;
+
+import timely.balancer.connection.TimelyBalancedHost;
+
+public interface HealthChecker {
+
+    public void setTimelyHosts(List<TimelyBalancedHost> timelyHosts);
+
+    public void close() throws Exception;
+}

balancer/src/main/java/timely/balancer/healthcheck/ServerHealthCheck.java

@@ -0,0 +1,8 @@
+package timely.balancer.healthcheck;
+
+import timely.balancer.connection.TimelyBalancedHost;
+
+public interface ServerHealthCheck {
+
+    public boolean isServerHealthy(TimelyBalancedHost timelyBalancedHost);
+}

balancer/src/main/java/timely/balancer/healthcheck/TCPServerHealthCheck.java

@@ -0,0 +1,33 @@
+package timely.balancer.healthcheck;
+
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.connection.tcp.TcpClientPool;
+import timely.client.tcp.TcpClient;
+
+public class TCPServerHealthCheck implements ServerHealthCheck {
+
+    final private TcpClientPool tcpClientPool;
+
+    public TCPServerHealthCheck(TcpClientPool tcpClientPool) {
+        this.tcpClientPool = tcpClientPool;
+    }
+
+    @Override
+    public boolean isServerHealthy(TimelyBalancedHost timelyBalancedHost) {
+
+        boolean healthy = true;
+        TcpClient client = null;
+        try {
+            client = tcpClientPool.borrowObject(timelyBalancedHost);
+            client.open();
+        } catch (Exception e) {
+            healthy = false;
+
+        } finally {
+            if (client != null) {
+                tcpClientPool.returnObject(timelyBalancedHost, client);
+            }
+        }
+        return healthy;
+    }
+}

balancer/src/main/java/timely/balancer/healthcheck/TcpHealthChecker.java

@@ -0,0 +1,62 @@
+package timely.balancer.healthcheck;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.connection.tcp.TcpClientPool;
+
+public class TcpHealthChecker implements HealthChecker {
+
+    private static final Logger LOG = LoggerFactory.getLogger(TcpHealthChecker.class);
+    private List<TimelyBalancedHost> timelyHosts = new ArrayList<>();
+    private ScheduledExecutorService executorService = Executors.newScheduledThreadPool(1);
+    final private TCPServerHealthCheck tcpServerHealthCheck;
+
+    public TcpHealthChecker(BalancerConfiguration config, TcpClientPool tcpClientPool) {
+        this.tcpServerHealthCheck = new TCPServerHealthCheck(tcpClientPool);
+        this.executorService.scheduleAtFixedRate(() -> {
+            synchronized (timelyHosts) {
+                for (TimelyBalancedHost h : timelyHosts) {
+                    try {
+                        if (tcpServerHealthCheck.isServerHealthy(h)) {
+                            h.reportSuccess();
+                        } else {
+                            h.reportFailure();
+                        }
+                    } catch (Exception e) {
+                        LOG.error(e.getMessage(), e);
+                        h.reportFailure();
+                    }
+                }
+            }
+        }, 0, config.getCheckServerHealthInterval(), TimeUnit.MILLISECONDS);
+    }
+
+    @Override
+    public void setTimelyHosts(List<TimelyBalancedHost> timelyHosts) {
+        synchronized (timelyHosts) {
+            this.timelyHosts.clear();
+            this.timelyHosts.addAll(timelyHosts);
+        }
+    }
+
+    public void close() throws Exception {
+        this.executorService.shutdown();
+        try {
+            this.executorService.awaitTermination(5, TimeUnit.SECONDS);
+        } catch (InterruptedException e) {
+
+        } finally {
+            if (!this.executorService.isTerminated()) {
+                this.executorService.shutdownNow();
+            }
+        }
+    }
+}

balancer/src/main/java/timely/balancer/netty/http/HttpRelayHandler.java

@@ -0,0 +1,205 @@
+package timely.balancer.netty.http;
+
+import static io.netty.handler.codec.http.HttpHeaderNames.CONTENT_LENGTH;
+
+import java.io.ByteArrayOutputStream;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+
+import com.google.common.collect.Multimap;
+import io.netty.buffer.Unpooled;
+import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.SimpleChannelInboundHandler;
+import io.netty.handler.codec.http.DefaultFullHttpResponse;
+import io.netty.handler.codec.http.FullHttpRequest;
+import io.netty.handler.codec.http.FullHttpResponse;
+import io.netty.handler.codec.http.HttpMethod;
+import io.netty.handler.codec.http.HttpResponseStatus;
+import io.netty.handler.codec.http.HttpVersion;
+import io.netty.util.ReferenceCountUtil;
+import org.apache.http.Header;
+import org.apache.http.client.methods.CloseableHttpResponse;
+import org.apache.http.client.methods.HttpGet;
+import org.apache.http.client.methods.HttpPost;
+import org.apache.http.client.methods.HttpUriRequest;
+import org.apache.http.entity.StringEntity;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.apache.http.message.BasicHeader;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.util.StreamUtils;
+import timely.api.request.AuthenticatedRequest;
+import timely.api.request.MetricRequest;
+import timely.api.request.timeseries.HttpRequest;
+import timely.api.request.timeseries.QueryRequest;
+import timely.api.response.TimelyException;
+import timely.auth.util.HttpHeaderUtils;
+import timely.auth.util.ProxiedEntityUtils;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.connection.http.HttpClientPool;
+import timely.balancer.resolver.MetricResolver;
+import timely.netty.http.TimelyHttpHandler;
+import timely.netty.http.auth.TimelyAuthenticationToken;
+
+public class HttpRelayHandler extends SimpleChannelInboundHandler<HttpRequest> implements TimelyHttpHandler {
+
+    private static final Logger LOG = LoggerFactory.getLogger(HttpRelayHandler.class);
+    private final HttpClientPool httpClientPool;
+    private MetricResolver metricResolver;
+
+    public HttpRelayHandler(MetricResolver metricResolver, HttpClientPool httpClientPool) {
+        this.metricResolver = metricResolver;
+        this.httpClientPool = httpClientPool;
+    }
+
+    @Override
+    public void channelRead0(ChannelHandlerContext ctx, HttpRequest msg) throws Exception {
+
+        CloseableHttpClient client = null;
+        TimelyBalancedHost k = null;
+        CloseableHttpResponse relayedResponse = null;
+        FullHttpRequest request = null;
+        try {
+            try {
+                request = msg.getHttpRequest();
+                String originalURI = request.uri();
+                originalURI = encodeURI(originalURI);
+
+                String metric = null;
+                if (msg instanceof QueryRequest) {
+                    Collection<QueryRequest.SubQuery> subqueries = ((QueryRequest) msg).getQueries();
+                    if (subqueries != null) {
+                        Iterator<QueryRequest.SubQuery> itr = subqueries.iterator();
+                        if (itr.hasNext()) {
+                            metric = itr.next().getMetric();
+                        }
+                    }
+                    k = metricResolver.getHostPortKey(metric);
+                } else if (msg instanceof MetricRequest) {
+                    metric = ((MetricRequest) msg).getMetric().getName();
+                    k = metricResolver.getHostPortKeyIngest(metric);
+                } else {
+                    k = metricResolver.getHostPortKey(null);
+                }
+                client = httpClientPool.borrowObject(k);
+
+                Multimap<String, String> headers = HttpHeaderUtils.toMultimap(request.headers());
+                if (msg instanceof AuthenticatedRequest) {
+                    AuthenticatedRequest authenticatedRequest = (AuthenticatedRequest) msg;
+                    TimelyAuthenticationToken token = authenticatedRequest.getToken();
+                    if (token != null) {
+                        if (token.getClientCert() != null) {
+                            ProxiedEntityUtils.addProxyHeaders(headers, token.getClientCert());
+                        }
+                    }
+                }
+
+                List<Header> relayedHeaderList = new ArrayList<>();
+                for (Map.Entry<String, String> h : headers.entries()) {
+                    if (!h.getKey().equals(CONTENT_LENGTH.toString())) {
+                        relayedHeaderList.add(new BasicHeader(h.getKey(), h.getValue()));
+                    }
+                }
+                Header[] headerArray = new Header[relayedHeaderList.size()];
+                relayedHeaderList.toArray(headerArray);
+
+                String relayURI = "https://" + k.getHost() + ":" + k.getHttpPort() + originalURI;
+                if (request.method().equals(HttpMethod.GET)) {
+                    HttpUriRequest relayedRequest = new HttpGet(relayURI);
+                    if (headerArray.length > 0) {
+                        relayedRequest.setHeaders(headerArray);
+                    }
+                    relayedResponse = client.execute(relayedRequest);
+
+                } else if (request.method().equals(HttpMethod.POST)) {
+                    HttpPost relayedRequest = new HttpPost(relayURI);
+
+                    String content = request.content().toString(StandardCharsets.UTF_8);
+                    StringEntity entity = new StringEntity(content);
+                    relayedRequest.setEntity(entity);
+                    if (headerArray.length > 0) {
+                        relayedRequest.setHeaders(headerArray);
+                    }
+                    relayedResponse = client.execute(relayedRequest);
+                }
+            } catch (Exception e) {
+                String message = e.getMessage();
+                if (message == null) {
+                    LOG.error("", e);
+                } else {
+                    if (message.contains("No matching tags")) {
+                        LOG.trace(message);
+                    } else {
+                        LOG.error(message, e);
+                    }
+                }
+                this.sendHttpError(ctx, new TimelyException(HttpResponseStatus.INTERNAL_SERVER_ERROR.code(),
+                        e.getMessage(), e.getLocalizedMessage(), e));
+                return;
+            } finally {
+                if (request != null && request instanceof AutoCloseable) {
+                    ReferenceCountUtil.release(request);
+                }
+            }
+            FullHttpResponse response = null;
+            if (relayedResponse == null) {
+                this.sendHttpError(ctx, new TimelyException(HttpResponseStatus.METHOD_NOT_ALLOWED.code(),
+                        "Method not allowed", "Method not allowed"));
+            } else {
+                ByteArrayOutputStream baos = new MyByteArrayOutputStream();
+                StreamUtils.copy(relayedResponse.getEntity().getContent(), baos);
+
+                response = new DefaultFullHttpResponse(HttpVersion.HTTP_1_1,
+                        HttpResponseStatus.valueOf(relayedResponse.getStatusLine().getStatusCode()),
+                        Unpooled.copiedBuffer(baos.toByteArray()));
+                for (Header h : relayedResponse.getAllHeaders()) {
+                    response.headers().add(h.getName(), h.getValue());
+                }
+                response.headers().set(CONTENT_LENGTH, response.content().readableBytes());
+                sendResponse(ctx, response);
+            }
+        } finally {
+            if (relayedResponse != null) {
+                relayedResponse.close();
+            }
+            if (client != null && k != null) {
+                httpClientPool.returnObject(k, client);
+            } else {
+                LOG.error("NOT RETURNING CONNECTION! " + msg.getHttpRequest().uri());
+            }
+        }
+    }
+
+    static public class MyByteArrayOutputStream extends ByteArrayOutputStream {
+
+        public MyByteArrayOutputStream() {
+        }
+
+        public MyByteArrayOutputStream(int size) {
+            super(size);
+        }
+
+        public int getCount() {
+            return count;
+        }
+
+        public byte[] getBuf() {
+            return buf;
+        }
+    }
+
+    static public String encodeURI(String s) {
+        try {
+            s = s.replaceAll("\\{", URLEncoder.encode("{", "UTF-8"));
+            s = s.replaceAll("\\}", URLEncoder.encode("}", "UTF-8"));
+        } catch (Exception e) {
+
+        }
+        return s;
+    }
+}

balancer/src/main/java/timely/balancer/netty/tcp/TcpRelayHandler.java

@@ -0,0 +1,99 @@
+package timely.balancer.netty.tcp;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
+import io.netty.buffer.Unpooled;
+import io.netty.channel.ChannelFuture;
+import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.SimpleChannelInboundHandler;
+import org.apache.commons.lang3.tuple.Pair;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.api.request.MetricRequest;
+import timely.api.request.TcpRequest;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.connection.tcp.TcpClientPool;
+import timely.balancer.resolver.BalancedMetricResolver;
+import timely.balancer.resolver.MetricResolver;
+import timely.client.tcp.TcpClient;
+import timely.netty.Constants;
+
+public class TcpRelayHandler extends SimpleChannelInboundHandler<TcpRequest> {
+
+    private static final Logger LOG = LoggerFactory.getLogger(TcpRelayHandler.class);
+    private static final String LOG_ERR_MSG = "Error storing put metric: {}";
+    private static final String ERR_MSG = "Error storing put metric: ";
+
+    private BalancedMetricResolver metricResolver;
+    private List<TcpClientPool> tcpClientPools;
+
+    public TcpRelayHandler(MetricResolver metricResolver, List<TcpClientPool> tcpClientPools) {
+        this.metricResolver = (BalancedMetricResolver) metricResolver;
+        this.tcpClientPools = tcpClientPools;
+    }
+
+    private TcpClientPool tcpClientPool() {
+        int x = Math.toIntExact(Thread.currentThread().getId() % tcpClientPools.size());
+        return tcpClientPools.get(x);
+    }
+
+    @Override
+    protected void channelRead0(ChannelHandlerContext ctx, TcpRequest msg) throws Exception {
+        LOG.trace("Received {}", msg);
+        try {
+            String line;
+            Pair<TimelyBalancedHost, TcpClient> keyClientPair = null;
+            try {
+                if (msg instanceof MetricRequest) {
+                    String metricName = ((MetricRequest) msg).getMetric().getName();
+                    line = ((MetricRequest) msg).getLine();
+                    keyClientPair = getClient(metricName, true);
+                } else {
+                    // Version request
+                    line = "version";
+                    keyClientPair = getClient(null, false);
+                }
+                keyClientPair.getRight().write(line + "\n");
+            } finally {
+                if (keyClientPair != null && keyClientPair.getLeft() != null && keyClientPair.getRight() != null) {
+                    tcpClientPool().returnObject(keyClientPair.getLeft(), keyClientPair.getRight());
+                }
+            }
+
+        } catch (IOException e) {
+            LOG.error(LOG_ERR_MSG, msg, e);
+            ChannelFuture cf = ctx.writeAndFlush(
+                    Unpooled.copiedBuffer((ERR_MSG + e.getMessage() + "\n").getBytes(StandardCharsets.UTF_8)));
+            if (!cf.isSuccess()) {
+                LOG.error(Constants.ERR_WRITING_RESPONSE, cf.cause());
+            }
+        }
+    }
+
+    private Pair<TimelyBalancedHost, TcpClient> getClient(String metric, boolean metricRequest) {
+        TcpClient client = null;
+        TimelyBalancedHost k = null;
+        int failures = 0;
+        while (client == null) {
+            try {
+                k = (metricRequest == true) ? metricResolver.getHostPortKeyIngest(metric)
+                        : metricResolver.getHostPortKey(metric);
+                client = tcpClientPool().borrowObject(k);
+            } catch (Exception e1) {
+                failures++;
+                client = null;
+                if (failures % 10 == 0) {
+                    LOG.error(e1.getMessage(), e1);
+                }
+                try {
+                    Thread.sleep(failures < 10 ? 500 : 60000);
+                } catch (InterruptedException e2) {
+                    // nothing
+                }
+            }
+        }
+        return Pair.of(k, client);
+    }
+}

balancer/src/main/java/timely/balancer/netty/udp/UdpRelayHandler.java

@@ -0,0 +1,83 @@
+package timely.balancer.netty.udp;
+
+import java.nio.charset.StandardCharsets;
+
+import io.netty.buffer.Unpooled;
+import io.netty.channel.ChannelFuture;
+import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.SimpleChannelInboundHandler;
+import org.apache.commons.lang3.tuple.Pair;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.api.request.MetricRequest;
+import timely.api.request.UdpRequest;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.connection.udp.UdpClientPool;
+import timely.balancer.resolver.MetricResolver;
+import timely.client.udp.UdpClient;
+import timely.netty.Constants;
+
+public class UdpRelayHandler extends SimpleChannelInboundHandler<UdpRequest> {
+
+    private static final Logger LOG = LoggerFactory.getLogger(UdpRelayHandler.class);
+    private static final String LOG_ERR_MSG = "Error storing put metric: {}";
+    private static final String ERR_MSG = "Error storing put metric: ";
+
+    private MetricResolver metricResolver;
+    private UdpClientPool udpClientPool;
+
+    public UdpRelayHandler(MetricResolver metricResolver, UdpClientPool udpClientPool) {
+        this.metricResolver = metricResolver;
+        this.udpClientPool = udpClientPool;
+    }
+
+    @Override
+    protected void channelRead0(ChannelHandlerContext ctx, UdpRequest msg) throws Exception {
+        LOG.trace("Received {}", msg);
+        try {
+            MetricRequest metricRequest = (MetricRequest) msg;
+            String metricName = metricRequest.getMetric().getName();
+            Pair<TimelyBalancedHost, UdpClient> keyClientPair = null;
+            try {
+                keyClientPair = getClient(metricName, true);
+                keyClientPair.getRight().write(metricRequest.getLine() + "\n");
+                keyClientPair.getRight().flush();
+            } finally {
+                if (keyClientPair != null && keyClientPair.getLeft() != null && keyClientPair.getRight() != null) {
+                    udpClientPool.returnObject(keyClientPair.getLeft(), keyClientPair.getRight());
+                }
+            }
+
+        } catch (Exception e) {
+            LOG.error(LOG_ERR_MSG, msg, e);
+            ChannelFuture cf = ctx.writeAndFlush(
+                    Unpooled.copiedBuffer((ERR_MSG + e.getMessage() + "\n").getBytes(StandardCharsets.UTF_8)));
+            if (!cf.isSuccess()) {
+                LOG.error(Constants.ERR_WRITING_RESPONSE, cf.cause());
+            }
+        }
+    }
+
+    private Pair<TimelyBalancedHost, UdpClient> getClient(String metric, boolean metricRequest) {
+        UdpClient client = null;
+        TimelyBalancedHost k = null;
+        int failures = 0;
+        while (client == null) {
+            try {
+                k = (metricRequest == true) ? metricResolver.getHostPortKeyIngest(metric)
+                        : metricResolver.getHostPortKey(metric);
+                client = udpClientPool.borrowObject(k);
+            } catch (Exception e1) {
+                failures++;
+                client = null;
+                LOG.error(e1.getMessage(), e1);
+                try {
+                    Thread.sleep(failures < 10 ? 500 : 60000);
+                } catch (InterruptedException e2) {
+                    // nothing
+                }
+            }
+        }
+        return Pair.of(k, client);
+    }
+}

balancer/src/main/java/timely/balancer/netty/ws/WsClientHandler.java

@@ -0,0 +1,93 @@
+package timely.balancer.netty.ws;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+import javax.websocket.CloseReason;
+import javax.websocket.EndpointConfig;
+import javax.websocket.Session;
+
+import com.google.common.collect.HashMultimap;
+import com.google.common.collect.Multimap;
+import io.netty.channel.ChannelHandlerContext;
+import io.netty.handler.codec.http.HttpResponseStatus;
+import io.netty.handler.codec.http.websocketx.PingWebSocketFrame;
+import io.netty.handler.codec.http.websocketx.TextWebSocketFrame;
+import io.netty.util.concurrent.ScheduledFuture;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.api.response.TimelyException;
+import timely.auth.util.ProxiedEntityUtils;
+import timely.client.websocket.ClientHandler;
+import timely.netty.http.auth.TimelyAuthenticationToken;
+
+public class WsClientHandler extends ClientHandler {
+
+    private static final Logger LOG = LoggerFactory.getLogger(WsClientHandler.class);
+    private final ChannelHandlerContext ctx;
+    private final TimelyAuthenticationToken token;
+    private ScheduledFuture<?> ping;
+
+    public WsClientHandler(ChannelHandlerContext ctx, TimelyAuthenticationToken token, int pingRate) {
+        this.ctx = ctx;
+        this.token = token;
+        this.ping = this.ctx.executor().scheduleAtFixedRate(() -> {
+            LOG.trace("Sending ping on channel {}", ctx.channel());
+            ctx.writeAndFlush(new PingWebSocketFrame());
+        }, pingRate, pingRate, TimeUnit.SECONDS);
+    }
+
+    @Override
+    public void beforeRequest(Map<String, List<String>> headers) {
+        if (token.getClientCert() != null) {
+            Multimap<String, String> proxyRequestHeaders = HashMultimap.create();
+            ProxiedEntityUtils.addProxyHeaders(proxyRequestHeaders, token.getClientCert());
+            for (String s : proxyRequestHeaders.keySet()) {
+                headers.put(s, new ArrayList<>(proxyRequestHeaders.get(s)));
+            }
+        }
+
+        Multimap<String, String> originalRequestHeaders = token.getHttpHeaders();
+        for (String s : originalRequestHeaders.keySet()) {
+            if (!headers.containsKey(s)) {
+                // add pre-existing values if key does not exist in proxyRequest
+                headers.put(s, new ArrayList<>(originalRequestHeaders.get(s)));
+            }
+        }
+    }
+
+    @Override
+    public void onOpen(Session session, EndpointConfig config) {
+        session.addMessageHandler(String.class, message -> {
+            ctx.writeAndFlush(new TextWebSocketFrame(message));
+            LOG.debug("Message received on Websocket session {}: {}", session.getId(), message);
+        });
+    }
+
+    @Override
+    public void onClose(Session session, CloseReason reason) {
+        super.onClose(session, reason);
+        if (!reason.getCloseCode().equals(CloseReason.CloseCodes.NORMAL_CLOSURE)) {
+            LOG.error("Abnormal close: " + reason.getReasonPhrase());
+            Exception e = new TimelyException(HttpResponseStatus.INTERNAL_SERVER_ERROR.code(), reason.getReasonPhrase(),
+                    "");
+            WsRelayHandler.sendErrorResponse(ctx, HttpResponseStatus.INTERNAL_SERVER_ERROR, e);
+        }
+        if (!ping.isCancelled()) {
+            ping.cancel(false);
+        }
+    }
+
+    @Override
+    public void onError(Session session, Throwable t) {
+        super.onError(session, t);
+        LOG.error(t.getMessage(), t);
+        Exception e = new TimelyException(HttpResponseStatus.INTERNAL_SERVER_ERROR.code(), t.getMessage(), "");
+        WsRelayHandler.sendErrorResponse(ctx, HttpResponseStatus.INTERNAL_SERVER_ERROR, e);
+        if (!ping.isCancelled()) {
+            ping.cancel(false);
+        }
+    }
+}

balancer/src/main/java/timely/balancer/netty/ws/WsClientHolder.java

@@ -0,0 +1,42 @@
+package timely.balancer.netty.ws;
+
+import java.io.IOException;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.connection.ws.WsClientPool;
+import timely.client.websocket.subscription.WebSocketSubscriptionClient;
+
+public class WsClientHolder {
+
+    private static final Logger LOG = LoggerFactory.getLogger(WsClientHolder.class);
+    private WebSocketSubscriptionClient client = null;
+    private TimelyBalancedHost host = null;
+
+    public WsClientHolder(TimelyBalancedHost host, WebSocketSubscriptionClient client) {
+        this.host = host;
+        this.client = client;
+    }
+
+    synchronized public WebSocketSubscriptionClient getClient() {
+        return client;
+    }
+
+    synchronized public TimelyBalancedHost getHost() {
+        return host;
+    }
+
+    synchronized public void close(WsClientPool wsClientPool) {
+        if (client != null && host != null) {
+            try {
+                client.close();
+            } catch (IOException e) {
+                LOG.error("Error closing web socket client", e);
+            }
+            wsClientPool.returnObject(host, client);
+            client = null;
+            host = null;
+        }
+    }
+}

balancer/src/main/java/timely/balancer/netty/ws/WsRelayHandler.java

@@ -0,0 +1,207 @@
+package timely.balancer.netty.ws;
+
+import java.net.ConnectException;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.datatype.jdk8.Jdk8Module;
+import com.google.common.collect.Multimap;
+import io.netty.channel.ChannelFuture;
+import io.netty.channel.ChannelFutureListener;
+import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.SimpleChannelInboundHandler;
+import io.netty.handler.codec.http.HttpResponseStatus;
+import io.netty.handler.codec.http.websocketx.CloseWebSocketFrame;
+import io.netty.handler.codec.http.websocketx.TextWebSocketFrame;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.api.request.subscription.AddSubscription;
+import timely.api.request.subscription.CloseSubscription;
+import timely.api.request.subscription.CreateSubscription;
+import timely.api.request.subscription.RemoveSubscription;
+import timely.api.request.subscription.SubscriptionRequest;
+import timely.api.response.TimelyException;
+import timely.auth.util.ProxiedEntityUtils;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.connection.ws.WsClientPool;
+import timely.balancer.resolver.MetricResolver;
+import timely.client.websocket.subscription.WebSocketSubscriptionClient;
+import timely.netty.http.TimelyHttpHandler;
+
+public class WsRelayHandler extends SimpleChannelInboundHandler<SubscriptionRequest> implements TimelyHttpHandler {
+
+    private static final Logger LOG = LoggerFactory.getLogger(WsRelayHandler.class);
+
+    private final BalancerConfiguration balancerConfig;
+    private final WsClientPool wsClientPool;
+    private MetricResolver metricResolver;
+    static private ObjectMapper mapper;
+    Map<String, Map<String, WsClientHolder>> wsClients = new ConcurrentHashMap<>();
+    Map<String, ChannelHandlerContext> wsSubscriptions = new ConcurrentHashMap<>();
+
+    static {
+        mapper = new ObjectMapper();
+        mapper.registerModule(new Jdk8Module());
+        mapper.configure(SerializationFeature.INDENT_OUTPUT, true);
+        mapper.configure(SerializationFeature.WRAP_EXCEPTIONS, true);
+        mapper.configure(SerializationFeature.WRAP_ROOT_VALUE, true);
+    }
+
+    public WsRelayHandler(BalancerConfiguration balancerConfig, MetricResolver metricResolver,
+            WsClientPool wsClientPool) {
+        this.balancerConfig = balancerConfig;
+        this.metricResolver = metricResolver;
+        this.wsClientPool = wsClientPool;
+    }
+
+    @Override
+    protected void channelRead0(ChannelHandlerContext ctx, SubscriptionRequest msg) throws Exception {
+        TimelyBalancedHost k;
+        ChannelHandlerContext origContext = null;
+        String subscriptionId;
+        try {
+            String metric = null;
+
+            Multimap<String, String> headers = msg.getRequestHeaders();
+            ProxiedEntityUtils.addProxyHeaders(headers, msg.getToken().getClientCert());
+
+            if (msg instanceof CreateSubscription) {
+                CreateSubscription create = (CreateSubscription) msg;
+                final String currentSubscriptionId = create.getSubscriptionId();
+                subscriptionId = currentSubscriptionId;
+                wsSubscriptions.put(subscriptionId, ctx);
+                // WebSocketSubscriptionClient sends the createSubscription when
+                // we call open
+                // We don't know where to send it to yet anyway because that
+                // depends on the metric.
+                ctx.channel().closeFuture().addListener(new ChannelFutureListener() {
+
+                    @Override
+                    public void operationComplete(ChannelFuture future) throws Exception {
+                        Map<String, WsClientHolder> metricToClientMap = wsClients.get(currentSubscriptionId);
+
+                        if (metricToClientMap != null) {
+                            synchronized (metricToClientMap) {
+                                // close all clients for this subscriptionId
+                                LOG.info("Channel closed, closing subscriptions for subscriptionId:%s",
+                                        currentSubscriptionId);
+                                for (Map.Entry<String, WsClientHolder> entry : metricToClientMap.entrySet()) {
+                                    entry.getValue().close(wsClientPool);
+                                }
+                                wsClients.remove(currentSubscriptionId);
+                                wsSubscriptions.remove(currentSubscriptionId);
+                            }
+                        }
+                    }
+                });
+
+            } else if (msg instanceof AddSubscription) {
+                AddSubscription add = (AddSubscription) msg;
+                metric = add.getMetric();
+                subscriptionId = add.getSubscriptionId();
+                origContext = wsSubscriptions.get(subscriptionId);
+                if (origContext == null) {
+                    // send error because user never sent a CreateSubscription
+                    // and we have nowhere to send the results
+                    LOG.info("ChannelHandlerContext not found for subscriptionId:%s - createSubscription not called?",
+                            subscriptionId);
+                    sendErrorResponse(ctx, HttpResponseStatus.BAD_REQUEST,
+                            new IllegalArgumentException("Must call create first"));
+                }
+                Map<String, WsClientHolder> metricToClientMap = wsClients.get(subscriptionId);
+                if (metricToClientMap == null) {
+                    metricToClientMap = new HashMap<>();
+                    wsClients.put(subscriptionId, metricToClientMap);
+                }
+                WebSocketSubscriptionClient client = null;
+                synchronized (metricToClientMap) {
+                    WsClientHolder hostClientHolder = metricToClientMap.get(metric);
+                    if (hostClientHolder == null) {
+                        k = metricResolver.getHostPortKey(metric);
+                        client = wsClientPool.borrowObject(k);
+                        client.open(new WsClientHandler(origContext, add.getToken(),
+                                (balancerConfig.getWebsocket().getTimeout() / 2)));
+                        metricToClientMap.put(metric, new WsClientHolder(k, client));
+                    } else {
+                        client = hostClientHolder.getClient();
+                    }
+                }
+                Map<String, String> tags = null;
+
+                Long startTime = 0L;
+                Long endTime = 0L;
+                Long delayTime = 5000L;
+                if (add.getTags().isPresent()) {
+                    tags = add.getTags().get();
+                }
+                if (add.getStartTime().isPresent()) {
+                    startTime = add.getStartTime().get();
+                }
+                if (add.getEndTime().isPresent()) {
+                    endTime = add.getEndTime().get();
+                }
+                if (add.getDelayTime().isPresent()) {
+                    delayTime = add.getDelayTime().get();
+                }
+
+                client.addSubscription(add.getMetric(), tags, startTime, endTime, delayTime);
+
+            } else if (msg instanceof RemoveSubscription) {
+                RemoveSubscription remove = (RemoveSubscription) msg;
+                metric = remove.getMetric();
+                subscriptionId = remove.getSubscriptionId();
+                Map<String, WsClientHolder> metricToClientMap = wsClients.get(subscriptionId);
+                if (metricToClientMap != null) {
+                    synchronized (metricToClientMap) {
+                        WsClientHolder hostClientHolder = metricToClientMap.get(metric);
+                        if (hostClientHolder != null) {
+                            hostClientHolder.getClient().removeSubscription(metric);
+                        } else {
+                            LOG.info("client not found for subscriptionId:%s metric:%s", subscriptionId, metric);
+                        }
+                    }
+                }
+            } else if (msg instanceof CloseSubscription) {
+                CloseSubscription close = (CloseSubscription) msg;
+                subscriptionId = close.getSubscriptionId();
+                Map<String, WsClientHolder> metricToClientMap = wsClients.get(subscriptionId);
+                if (metricToClientMap != null) {
+                    synchronized (metricToClientMap) {
+                        // close all clients for this subscriptionId
+                        for (Map.Entry<String, WsClientHolder> entry : metricToClientMap.entrySet()) {
+                            entry.getValue().close(wsClientPool);
+                        }
+                    }
+                    wsClients.remove(subscriptionId);
+                    wsSubscriptions.remove(subscriptionId);
+                }
+                ctx.writeAndFlush(new CloseWebSocketFrame(1000, "Client requested close."));
+            }
+        } catch (ConnectException e1) {
+            LOG.error(e1.getMessage(), e1);
+            ChannelHandlerContext errorCtx = origContext == null ? ctx : origContext;
+            sendErrorResponse(errorCtx, HttpResponseStatus.INTERNAL_SERVER_ERROR, e1);
+        } catch (Exception e2) {
+            LOG.error(e2.getMessage(), e2);
+            ChannelHandlerContext errorCtx = origContext == null ? ctx : origContext;
+            sendErrorResponse(errorCtx, HttpResponseStatus.INTERNAL_SERVER_ERROR, e2);
+        }
+
+    }
+
+    static public void sendErrorResponse(ChannelHandlerContext ctx, HttpResponseStatus status, Exception ex) {
+
+        try {
+            TimelyException te = new TimelyException(status.code(), ex.getMessage(), ex.getMessage());
+            String json = mapper.writeValueAsString(te);
+            ctx.writeAndFlush(new TextWebSocketFrame(json));
+        } catch (JsonProcessingException e) {
+            LOG.error("Error serializing exception");
+        }
+    }
+}

balancer/src/main/java/timely/balancer/resolver/BalancedMetricResolver.java

@@ -0,0 +1,988 @@
+package timely.balancer.resolver;
+
+import static timely.Server.SERVICE_DISCOVERY_PATH;
+import static timely.balancer.Balancer.ASSIGNMENTS_LAST_UPDATED_PATH;
+import static timely.balancer.Balancer.ASSIGNMENTS_LOCK_PATH;
+import static timely.balancer.Balancer.LEADER_LATCH_PATH;
+import static timely.balancer.resolver.eventing.MetricAssignedEvent.Reason.ASSIGN_FALLBACK_SEQUENTIAL;
+import static timely.balancer.resolver.eventing.MetricAssignedEvent.Reason.ASSIGN_ROUND_ROBIN;
+import static timely.balancer.resolver.eventing.MetricAssignedEvent.Reason.HOST_DOWN_ROUND_ROBIN;
+import static timely.balancer.resolver.eventing.MetricAssignedEvent.Reason.HOST_REMOVED;
+import static timely.balancer.resolver.eventing.MetricAssignedEvent.Reason.REBALANCE;
+import static timely.store.cache.DataStoreCache.NON_CACHED_METRICS;
+import static timely.store.cache.DataStoreCache.NON_CACHED_METRICS_LOCK_PATH;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.TreeSet;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+
+import org.apache.commons.lang.StringUtils;
+import org.apache.commons.lang3.SerializationUtils;
+import org.apache.curator.framework.CuratorFramework;
+import org.apache.curator.framework.recipes.atomic.DistributedAtomicValue;
+import org.apache.curator.framework.recipes.cache.TreeCache;
+import org.apache.curator.framework.recipes.cache.TreeCacheEvent;
+import org.apache.curator.framework.recipes.cache.TreeCacheListener;
+import org.apache.curator.framework.recipes.leader.LeaderLatch;
+import org.apache.curator.framework.recipes.leader.LeaderLatchListener;
+import org.apache.curator.framework.recipes.locks.InterProcessReadWriteLock;
+import org.apache.curator.framework.state.ConnectionState;
+import org.apache.curator.retry.RetryForever;
+import org.apache.curator.x.discovery.ServiceCache;
+import org.apache.curator.x.discovery.ServiceDiscovery;
+import org.apache.curator.x.discovery.ServiceDiscoveryBuilder;
+import org.apache.curator.x.discovery.ServiceInstance;
+import org.apache.curator.x.discovery.details.ServiceCacheListener;
+import org.apache.zookeeper.CreateMode;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.ServerDetails;
+import timely.balancer.ArrivalRate;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.healthcheck.HealthChecker;
+import timely.balancer.resolver.eventing.MetricAssignedCallback;
+import timely.balancer.resolver.eventing.MetricAssignedEvent;
+import timely.balancer.resolver.eventing.MetricBalanceCallback;
+import timely.balancer.resolver.eventing.MetricBalanceEvent;
+import timely.balancer.resolver.eventing.MetricHostCallback;
+import timely.balancer.resolver.eventing.MetricHostEvent;
+
+public class BalancedMetricResolver implements MetricResolver {
+
+    private static final Logger LOG = LoggerFactory.getLogger(BalancedMetricResolver.class);
+    private Map<String, TimelyBalancedHost> metricToHostMap = new TreeMap<>();
+    private Set<String> unassignedMetrics = new HashSet<>();
+    private Map<String, ArrivalRate> metricMap = new HashMap<>();
+    private ReentrantReadWriteLock balancerLock = new ReentrantReadWriteLock();
+    private List<TimelyBalancedHost> serverList = new ArrayList<>();
+    private Random r = new Random();
+    private final HealthChecker healthChecker;
+    private ScheduledExecutorService assignmentExecutor = Executors.newScheduledThreadPool(2);
+    private ScheduledExecutorService arrivalRateExecutor = Executors.newScheduledThreadPool(2);
+    private int roundRobinCounter = 0;
+    private Set<String> nonCachedMetrics = new HashSet<>();
+    private DistributedAtomicValue nonCachedMetricsIP;
+    private ReentrantReadWriteLock nonCachedMetricsLocalLock = new ReentrantReadWriteLock();
+    private InterProcessReadWriteLock nonCachedMetricsIPRWLock;
+    private AtomicLong assignmentsLastUpdatedLocal = new AtomicLong(0);
+    private LeaderLatch leaderLatch;
+    private AtomicBoolean isLeader = new AtomicBoolean(false);
+    private InterProcessReadWriteLock assignmentsIPRWLock;
+    private MetricAssignmentPerister assignmentPerister;
+
+    final private BalancerConfiguration balancerConfig;
+    final private CuratorFramework curatorFramework;
+
+    private List<MetricAssignedCallback> metricAssignedCallbacks = new ArrayList<>();
+    private List<MetricBalanceCallback> metricBalanceCallbacks = new ArrayList<>();
+    private List<MetricHostCallback> metricHostCallbacks = new ArrayList<>();
+
+    public enum BalanceType {
+        HIGH_LOW, HIGH_AVG, AVG_LOW;
+    }
+
+    public BalancedMetricResolver(CuratorFramework curatorFramework, BalancerConfiguration balancerConfig,
+            HealthChecker healthChecker) {
+        this.curatorFramework = curatorFramework;
+        this.balancerConfig = balancerConfig;
+        this.healthChecker = healthChecker;
+    }
+
+    public void start() {
+        assignmentsIPRWLock = new InterProcessReadWriteLock(curatorFramework, ASSIGNMENTS_LOCK_PATH);
+        testIPRWLock(curatorFramework, assignmentsIPRWLock, ASSIGNMENTS_LOCK_PATH);
+
+        this.assignmentPerister = new MetricAssignmentPerister(this, balancerConfig, metricToHostMap, nonCachedMetrics,
+                curatorFramework, assignmentsIPRWLock, nonCachedMetricsLocalLock, assignmentsLastUpdatedLocal,
+                balancerLock);
+
+        startLeaderLatch(curatorFramework);
+        startServiceListener(curatorFramework);
+
+        TreeCacheListener assignmentListener = (curatorFramework1, event) -> {
+            LOG.debug("Handling assignments event {}. assignmentsLastUpdated:{}", event.getType().toString(),
+                    new Date(assignmentPerister.getAssignmentsLastUpdatedByLeader()));
+            if (event.getType().equals(TreeCacheEvent.Type.NODE_UPDATED)) {
+                assignmentPerister.readAssignments(true);
+            }
+        };
+
+        try (TreeCache assignmentTreeCache = new TreeCache(curatorFramework, ASSIGNMENTS_LAST_UPDATED_PATH)) {
+            assignmentTreeCache.getListenable().addListener(assignmentListener);
+            assignmentTreeCache.start();
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        }
+
+        nonCachedMetricsIPRWLock = new InterProcessReadWriteLock(curatorFramework, NON_CACHED_METRICS_LOCK_PATH);
+        testIPRWLock(curatorFramework, nonCachedMetricsIPRWLock, NON_CACHED_METRICS_LOCK_PATH);
+        nonCachedMetricsIP = new DistributedAtomicValue(curatorFramework, NON_CACHED_METRICS, new RetryForever(1000));
+        TreeCacheListener nonCachedMetricsListener = new TreeCacheListener() {
+
+            @Override
+            public void childEvent(CuratorFramework curatorFramework, TreeCacheEvent event) throws Exception {
+                if (event.getType().equals(TreeCacheEvent.Type.NODE_UPDATED)) {
+                    LOG.debug("Handling nonCachedMetricsIP event {}", event.getType().toString());
+                    readNonCachedMetricsIP();
+                }
+            }
+        };
+
+        try (TreeCache nonCachedMetricsTreeCache = new TreeCache(curatorFramework, NON_CACHED_METRICS)) {
+            nonCachedMetricsTreeCache.getListenable().addListener(nonCachedMetricsListener);
+            nonCachedMetricsTreeCache.start();
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        }
+
+        nonCachedMetricsLocalLock.writeLock().lock();
+        try {
+            addNonCachedMetrics(balancerConfig.getCache().getNonCachedMetrics());
+        } finally {
+            nonCachedMetricsLocalLock.writeLock().unlock();
+        }
+        readNonCachedMetricsIP();
+
+        assignmentPerister.readAssignments(false);
+
+        assignmentExecutor.scheduleAtFixedRate(() -> {
+            if (isLeader.get()) {
+                try {
+                    balance();
+                } catch (Exception e) {
+                    LOG.error(e.getMessage(), e);
+                }
+            }
+        }, balancerConfig.getBalanceDelay(), balancerConfig.getBalancePeriod(), TimeUnit.MILLISECONDS);
+
+        assignmentExecutor.scheduleAtFixedRate(() -> {
+            try {
+                if (isLeader.get()) {
+                    long lastLocalUpdate = assignmentsLastUpdatedLocal.get();
+                    long lastUpdateByLeader = assignmentPerister.getAssignmentsLastUpdatedByLeader();
+                    if (lastLocalUpdate > lastUpdateByLeader) {
+                        LOG.debug("Leader writing assignments lastLocalUpdate ({}) > lastUpdateByLeader ({})",
+                                new Date(lastLocalUpdate), new Date(lastUpdateByLeader));
+                        assignmentPerister.writeAssignments();
+                    } else {
+                        LOG.trace("Leader not writing assignments lastLocalUpdate ({}) <= lastUpdateByLeader ({})",
+                                new Date(lastLocalUpdate), new Date(lastUpdateByLeader));
+                    }
+                } else {
+                    assignmentPerister.readAssignments(true);
+                }
+            } catch (Exception e) {
+                LOG.error(e.getMessage(), e);
+            }
+        }, balancerConfig.getPersistDelay(), balancerConfig.getPersistPeriod(), TimeUnit.MILLISECONDS);
+    }
+
+    private void readNonCachedMetricsIP() {
+
+        Set<String> currentNonCachedMetricsDistributed = new TreeSet<>();
+        try {
+            boolean acquired = false;
+            while (!acquired) {
+                acquired = nonCachedMetricsIPRWLock.readLock().acquire(60, TimeUnit.SECONDS);
+            }
+            byte[] currentNonCachedMetricsDistributedBytes = nonCachedMetricsIP.get().postValue();
+            if (currentNonCachedMetricsDistributedBytes != null) {
+                try {
+                    currentNonCachedMetricsDistributed = SerializationUtils
+                            .deserialize(currentNonCachedMetricsDistributedBytes);
+                } catch (Exception e) {
+                    LOG.error(e.getMessage(), e);
+                    currentNonCachedMetricsDistributed = new TreeSet<>();
+                }
+            }
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        } finally {
+            try {
+                nonCachedMetricsIPRWLock.readLock().release();
+            } catch (Exception e) {
+                LOG.error(e.getMessage(), e);
+            }
+        }
+
+        nonCachedMetricsLocalLock.writeLock().lock();
+        try {
+            if (nonCachedMetrics.containsAll(currentNonCachedMetricsDistributed)) {
+                LOG.debug("local nonCachedMetrics already contains {}", currentNonCachedMetricsDistributed);
+            } else {
+                currentNonCachedMetricsDistributed.removeAll(nonCachedMetrics);
+                LOG.debug("Adding {} to local nonCachedMetrics", currentNonCachedMetricsDistributed);
+                nonCachedMetrics.addAll(currentNonCachedMetricsDistributed);
+            }
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        } finally {
+            nonCachedMetricsLocalLock.writeLock().unlock();
+        }
+    }
+
+    private void startLeaderLatch(CuratorFramework curatorFramework) {
+        try {
+
+            this.leaderLatch = new LeaderLatch(curatorFramework, LEADER_LATCH_PATH);
+            this.leaderLatch.start();
+            this.leaderLatch.addListener(new LeaderLatchListener() {
+
+                @Override
+                public void isLeader() {
+                    LOG.info("this balancer is the leader");
+                    isLeader.set(true);
+                    assignmentPerister.writeAssignments();
+                }
+
+                @Override
+                public void notLeader() {
+                    LOG.info("this balancer is not the leader");
+                    isLeader.set(false);
+                }
+            });
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        }
+    }
+
+    private void startServiceListener(CuratorFramework curatorFramework) {
+        try {
+            ServiceDiscovery<ServerDetails> discovery = ServiceDiscoveryBuilder.builder(ServerDetails.class)
+                    .client(curatorFramework).basePath(SERVICE_DISCOVERY_PATH).build();
+            discovery.start();
+            Collection<ServiceInstance<ServerDetails>> instances = discovery.queryForInstances("timely-server");
+
+            balancerLock.writeLock().lock();
+            try {
+                for (ServiceInstance<ServerDetails> si : instances) {
+                    ServerDetails pl = si.getPayload();
+                    TimelyBalancedHost tbh = TimelyBalancedHost.of(pl.getHost(), pl.getTcpPort(), pl.getHttpPort(),
+                            pl.getWsPort(), pl.getUdpPort(), new ArrivalRate(arrivalRateExecutor));
+                    LOG.info("adding service {} host:{}", si.getId(), TimelyBalancedHost.toStringShort(tbh));
+                    tbh.setBalancerConfig(balancerConfig);
+                    serverList.add(tbh);
+                    metricHostEvent(tbh, MetricHostEvent.ActionType.ADDED);
+                }
+                healthChecker.setTimelyHosts(serverList);
+            } finally {
+                balancerLock.writeLock().unlock();
+            }
+
+            final ServiceCache<ServerDetails> serviceCache = discovery.serviceCacheBuilder().name("timely-server")
+                    .build();
+            ServiceCacheListener listener = new ServiceCacheListener() {
+
+                @Override
+                public void cacheChanged() {
+                    boolean rebalanceNeeded = false;
+                    balancerLock.writeLock().lock();
+                    try {
+                        List<ServiceInstance<ServerDetails>> instances = serviceCache.getInstances();
+                        Set<TimelyBalancedHost> availableHosts = new HashSet<>();
+                        for (ServiceInstance<ServerDetails> si : instances) {
+                            ServerDetails pl = (ServerDetails) si.getPayload();
+                            TimelyBalancedHost tbh = TimelyBalancedHost.of(pl.getHost(), pl.getTcpPort(),
+                                    pl.getHttpPort(), pl.getWsPort(), pl.getUdpPort(),
+                                    new ArrivalRate(arrivalRateExecutor));
+                            tbh.setBalancerConfig(balancerConfig);
+                            availableHosts.add(tbh);
+                        }
+
+                        List<String> reassignMetrics = new ArrayList<>();
+                        // remove hosts that are no longer available
+                        Iterator<TimelyBalancedHost> itr = serverList.iterator();
+                        while (itr.hasNext()) {
+                            TimelyBalancedHost h = itr.next();
+                            if (availableHosts.contains(h)) {
+                                availableHosts.remove(h);
+                            } else {
+                                itr.remove();
+                                metricHostEvent(h, MetricHostEvent.ActionType.REMOVED);
+                                LOG.info("removing service {}", TimelyBalancedHost.toStringShort(h));
+                                for (Map.Entry<String, TimelyBalancedHost> e : metricToHostMap.entrySet()) {
+                                    if (e.getValue().equals(h)) {
+                                        reassignMetrics.add(e.getKey());
+                                    }
+                                }
+                                rebalanceNeeded = true;
+                            }
+                        }
+
+                        // add new hosts that were not previously known
+                        for (TimelyBalancedHost h : availableHosts) {
+                            LOG.info("adding service {}", TimelyBalancedHost.toStringShort(h));
+                            serverList.add(h);
+                            metricHostEvent(h, MetricHostEvent.ActionType.ADDED);
+                            rebalanceNeeded = true;
+                        }
+                        healthChecker.setTimelyHosts(serverList);
+                        if (!availableHosts.isEmpty()) {
+                            reassignMetrics.addAll(unassignedMetrics);
+                            unassignedMetrics.clear();
+                        }
+                        if (isLeader.get()) {
+                            for (String s : reassignMetrics) {
+                                TimelyBalancedHost h = getRoundRobinHost(null);
+                                assignMetric(s, h, HOST_REMOVED);
+                                LOG.debug("Assigned server removed.  Assigning {} to server {}", s,
+                                        TimelyBalancedHost.toStringShort(h));
+                            }
+                        }
+
+                    } finally {
+                        balancerLock.writeLock().unlock();
+                    }
+                    if (isLeader.get()) {
+                        if (rebalanceNeeded) {
+                            balance();
+                        }
+                        assignmentPerister.writeAssignments();
+                    }
+                }
+
+                @Override
+                public void stateChanged(CuratorFramework curatorFramework, ConnectionState connectionState) {
+                    LOG.info("serviceCache state changed.  Connected:{}", connectionState.isConnected());
+                }
+            };
+            serviceCache.addListener(listener);
+            serviceCache.start();
+
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        }
+    }
+
+    private TimelyBalancedHost getLeastUsedHost() {
+
+        TimelyBalancedHost tbh = null;
+        balancerLock.readLock().lock();
+        try {
+            Map<Double, TimelyBalancedHost> rateSortedHosts = new TreeMap<>();
+            for (TimelyBalancedHost s : serverList) {
+                rateSortedHosts.put(s.getArrivalRate(), s);
+            }
+
+            Iterator<Map.Entry<Double, TimelyBalancedHost>> itr = rateSortedHosts.entrySet().iterator();
+
+            while (itr.hasNext() && tbh == null) {
+                TimelyBalancedHost currentTBH = itr.next().getValue();
+                if (currentTBH.isUp()) {
+                    tbh = currentTBH;
+                }
+            }
+        } finally {
+            balancerLock.readLock().unlock();
+        }
+        return tbh;
+    }
+
+    private TimelyBalancedHost getRandomHost(TimelyBalancedHost notThisOne) {
+
+        TimelyBalancedHost tbh = null;
+        balancerLock.readLock().lock();
+        try {
+            for (int x = 0; tbh == null && x < serverList.size(); x++) {
+                tbh = serverList.get(Math.abs(r.nextInt() & Integer.MAX_VALUE) % serverList.size());
+                if (!tbh.isUp()) {
+                    tbh = null;
+                } else if (notThisOne != null && tbh.equals(notThisOne)) {
+                    tbh = null;
+                }
+            }
+        } finally {
+            balancerLock.readLock().unlock();
+        }
+        return tbh;
+    }
+
+    protected TimelyBalancedHost getRoundRobinHost(TimelyBalancedHost notThisOne) {
+        TimelyBalancedHost tbh = null;
+        balancerLock.readLock().lock();
+        try {
+            int maxAttempts = serverList.size();
+            int currentAttempt = 0;
+            while (tbh == null && currentAttempt < maxAttempts) {
+                try {
+                    currentAttempt++;
+                    tbh = serverList.get(roundRobinCounter % serverList.size());
+                    if (!tbh.isUp()) {
+                        tbh = null;
+                    }
+                    if (notThisOne != null && notThisOne.equals(tbh)) {
+                        tbh = null;
+                    }
+                } finally {
+                    roundRobinCounter++;
+                    if (roundRobinCounter == Integer.MAX_VALUE) {
+                        roundRobinCounter = 0;
+                    }
+                }
+            }
+            if (tbh == null) {
+                tbh = getRandomHost(notThisOne);
+            }
+        } finally {
+            balancerLock.readLock().unlock();
+        }
+        return tbh;
+    }
+
+    private TimelyBalancedHost chooseHost(Set<TimelyBalancedHost> potentialHosts,
+            Map<TimelyBalancedHost, Double> calculatedRates, double referenceRate, BalanceType balanceType) {
+
+        TimelyBalancedHost tbh = null;
+        Map<Long, TimelyBalancedHost> weightedList = new TreeMap<>();
+        long cumulativeWeight = 0;
+        for (TimelyBalancedHost h : potentialHosts) {
+            double currentDiff;
+            if (balanceType.equals(BalanceType.HIGH_LOW) || balanceType.equals(BalanceType.HIGH_AVG)) {
+                currentDiff = referenceRate - calculatedRates.get(h);
+            } else {
+                currentDiff = calculatedRates.get(h) - referenceRate;
+            }
+            cumulativeWeight += Math.round(currentDiff);
+            weightedList.put(cumulativeWeight, h);
+        }
+
+        if (cumulativeWeight > 0) {
+            long randomWeight = r.nextLong() % cumulativeWeight;
+            for (Map.Entry<Long, TimelyBalancedHost> e : weightedList.entrySet()) {
+                if (randomWeight <= e.getKey()) {
+                    tbh = e.getValue();
+                    break;
+                }
+            }
+        }
+        return tbh;
+    }
+
+    private int balance() {
+
+        int numReassigned = 0;
+        if (isLeader.get()) {
+            double controlBandPercentage = balancerConfig.getControlBandPercentage();
+            // save current rates so that we can modify
+            double totalArrivalRate = 0;
+            Map<TimelyBalancedHost, Double> calculatedRates = new HashMap<>();
+            for (TimelyBalancedHost h : serverList) {
+                double tbhArrivalRate = h.getArrivalRate();
+                calculatedRates.put(h, tbhArrivalRate);
+                totalArrivalRate += tbhArrivalRate;
+            }
+            double averageArrivalRate = totalArrivalRate / serverList.size();
+
+            Set<TimelyBalancedHost> highHosts = new HashSet<>();
+            Set<TimelyBalancedHost> lowHosts = new HashSet<>();
+            Set<TimelyBalancedHost> avgHosts = new HashSet<>();
+
+            double controlHighLimit = averageArrivalRate * (1.0 + controlBandPercentage);
+            double controlLowLimit = averageArrivalRate * (1.0 - controlBandPercentage);
+
+            for (TimelyBalancedHost h : serverList) {
+                if (h.isUp()) {
+                    double currRate = calculatedRates.get(h);
+                    if (currRate < controlLowLimit) {
+                        lowHosts.add(h);
+                    } else if (currRate > controlHighLimit) {
+                        highHosts.add(h);
+                    } else {
+                        avgHosts.add(h);
+                    }
+                }
+            }
+
+            if (highHosts.isEmpty() && lowHosts.isEmpty()) {
+                LOG.debug("Host's arrival rates are within {} of the average", controlBandPercentage);
+            } else if (!highHosts.isEmpty() && !lowHosts.isEmpty()) {
+                LOG.debug("begin rebalancing {}", BalanceType.HIGH_LOW);
+                numReassigned = rebalance(highHosts, lowHosts, calculatedRates, averageArrivalRate,
+                        BalanceType.HIGH_LOW);
+                LOG.debug("end rebalancing {} - reassigned {}", BalanceType.HIGH_LOW, numReassigned);
+            } else if (lowHosts.isEmpty()) {
+                LOG.debug("begin rebalancing {}", BalanceType.HIGH_AVG);
+                numReassigned = rebalance(highHosts, avgHosts, calculatedRates, averageArrivalRate,
+                        BalanceType.HIGH_AVG);
+                LOG.debug("end rebalancing {} - reassigned {}", BalanceType.HIGH_AVG, numReassigned);
+            } else {
+                LOG.debug("begin rebalancing {}", BalanceType.AVG_LOW);
+                numReassigned = rebalance(avgHosts, lowHosts, calculatedRates, averageArrivalRate, BalanceType.AVG_LOW);
+                LOG.debug("end rebalancing {} - reassigned {}", BalanceType.AVG_LOW, numReassigned);
+            }
+        }
+        return numReassigned;
+    }
+
+    public int rebalance(Set<TimelyBalancedHost> losingHosts, Set<TimelyBalancedHost> gainingHosts,
+            Map<TimelyBalancedHost, Double> calculatedRates, double targetArrivalRate, BalanceType balanceType) {
+
+        int numReassigned = 0;
+        if (isLeader.get()) {
+            metricBalanceEvent(MetricBalanceEvent.ProgressType.BEGIN, balanceType, 0);
+            balancerLock.writeLock().lock();
+            try {
+                metricBalanceEvent(MetricBalanceEvent.ProgressType.BALANCER_LOCK_ACQUIRED, balanceType, 0);
+                Map<String, ArrivalRate> tempMetricMap = new HashMap<>();
+                tempMetricMap.putAll(metricMap);
+
+                Set<TimelyBalancedHost> focusedHosts;
+                Set<TimelyBalancedHost> selectFromHosts;
+                if (balanceType.equals(BalanceType.HIGH_LOW) || balanceType.equals(BalanceType.HIGH_AVG)) {
+                    focusedHosts = losingHosts;
+                    selectFromHosts = gainingHosts;
+                } else {
+                    focusedHosts = gainingHosts;
+                    selectFromHosts = losingHosts;
+                }
+
+                for (TimelyBalancedHost h : focusedHosts) {
+                    double desiredChange;
+                    if (balanceType.equals(BalanceType.HIGH_LOW) || balanceType.equals(BalanceType.HIGH_AVG)) {
+                        desiredChange = h.getArrivalRate() - targetArrivalRate;
+                    } else {
+                        desiredChange = targetArrivalRate - h.getArrivalRate();
+                    }
+
+                    // sort metrics by rate
+                    Map<Double, String> rateSortedMetrics = new TreeMap<>(Collections.reverseOrder());
+                    for (Map.Entry<String, ArrivalRate> e : tempMetricMap.entrySet()) {
+                        if (metricToHostMap.get(e.getKey()).equals(h)) {
+                            rateSortedMetrics.put(e.getValue().getRate(), e.getKey());
+                        }
+                    }
+
+                    LOG.trace("focusHost {} desiredChange:{} rateSortedMetrics.size():{}",
+                            TimelyBalancedHost.toStringShort(h), desiredChange, rateSortedMetrics.size());
+
+                    boolean doneWithHost = false;
+                    while (!doneWithHost) {
+                        Iterator<Map.Entry<Double, String>> itr = rateSortedMetrics.entrySet().iterator();
+                        while (!doneWithHost && itr.hasNext()) {
+                            Map.Entry<Double, String> e = null;
+                            // find largest metric that does not exceed desired change
+                            while (e == null && itr.hasNext()) {
+                                e = itr.next();
+                                if (e.getKey() > desiredChange) {
+                                    LOG.trace("Skipping:{} rate:{}", e.getValue(), e.getKey());
+                                    e = null;
+                                }
+                            }
+
+                            if (e == null) {
+                                LOG.trace("no metric small enough");
+                                doneWithHost = true;
+                            } else {
+                                LOG.trace("Selected:{} rate:{}", e.getValue(), e.getKey());
+                                TimelyBalancedHost candidateHost = chooseHost(selectFromHosts, calculatedRates,
+                                        calculatedRates.get(h), balanceType);
+                                if (candidateHost == null) {
+                                    LOG.trace("candidate host is null");
+                                    doneWithHost = true;
+                                } else {
+                                    String metric = e.getValue();
+                                    Double metricRate = e.getKey();
+                                    assignMetric(metric, candidateHost, REBALANCE);
+                                    numReassigned++;
+                                    calculatedRates.put(candidateHost, calculatedRates.get(candidateHost) + metricRate);
+                                    calculatedRates.put(h, calculatedRates.get(h) - metricRate);
+                                    desiredChange -= metricRate;
+                                    // don't move this metric again this host or balance
+                                    itr.remove();
+                                    tempMetricMap.remove(metric);
+                                    LOG.info(
+                                            "rebalancing: reassigning metric:{} rate:{} from server {} to {} remaining delta {}",
+                                            metric, metricRate, TimelyBalancedHost.toStringShort(h),
+                                            TimelyBalancedHost.toStringShort(candidateHost), desiredChange);
+                                }
+                            }
+                        }
+                        if (!itr.hasNext()) {
+                            LOG.trace("Reached end or rateSortedMetrics");
+                            doneWithHost = true;
+                        }
+                        if (balanceType.equals(BalanceType.HIGH_LOW) || balanceType.equals(BalanceType.HIGH_AVG)) {
+                            if (calculatedRates.get(h) <= targetArrivalRate) {
+                                doneWithHost = true;
+                                LOG.trace("calculatedRates.get(h) <= targetArivalRate");
+                            }
+                        } else {
+                            if (calculatedRates.get(h) >= targetArrivalRate) {
+                                doneWithHost = true;
+                                LOG.trace("calculatedRates.get(h) >= targetArivalRate");
+                            }
+                        }
+                    }
+                }
+            } finally {
+                balancerLock.writeLock().unlock();
+                metricBalanceEvent(MetricBalanceEvent.ProgressType.END, balanceType, numReassigned);
+            }
+        }
+        return numReassigned;
+    }
+
+    private void addNonCachedMetrics(Collection<String> nonCachedMetricsUpdate) {
+        if (!nonCachedMetricsUpdate.isEmpty()) {
+            try {
+                LOG.debug("Adding {} to local nonCachedMetrics", nonCachedMetricsUpdate);
+                nonCachedMetricsLocalLock.writeLock().lock();
+                try {
+                    nonCachedMetrics.addAll(nonCachedMetricsUpdate);
+                } finally {
+                    nonCachedMetricsLocalLock.writeLock().unlock();
+                }
+
+                try {
+                    boolean acquired = false;
+                    while (!acquired) {
+                        acquired = nonCachedMetricsIPRWLock.writeLock().acquire(60, TimeUnit.SECONDS);
+                    }
+                    byte[] currentNonCachedMetricsDistributedBytes = nonCachedMetricsIP.get().postValue();
+                    Set<String> currentNonCachedMetricsIP;
+                    if (currentNonCachedMetricsDistributedBytes == null) {
+                        currentNonCachedMetricsIP = new TreeSet<>();
+                    } else {
+                        currentNonCachedMetricsIP = SerializationUtils
+                                .deserialize(currentNonCachedMetricsDistributedBytes);
+                    }
+                    if (currentNonCachedMetricsIP.containsAll(nonCachedMetricsUpdate)) {
+                        LOG.debug("nonCachedMetricsIP already contains {}", nonCachedMetricsUpdate);
+                    } else {
+                        nonCachedMetricsUpdate.removeAll(currentNonCachedMetricsIP);
+                        LOG.debug("Adding {} to nonCachedMetricsIP", nonCachedMetricsUpdate);
+                        TreeSet<String> updateSet = new TreeSet<>();
+                        updateSet.addAll(currentNonCachedMetricsIP);
+                        updateSet.addAll(nonCachedMetricsUpdate);
+                        byte[] updateValue = SerializationUtils.serialize(updateSet);
+                        nonCachedMetricsIP.trySet(updateValue);
+                        if (!nonCachedMetricsIP.get().succeeded()) {
+                            nonCachedMetricsIP.forceSet(updateValue);
+                        }
+                    }
+                } finally {
+                    nonCachedMetricsIPRWLock.writeLock().release();
+                }
+            } catch (Exception e) {
+                LOG.error(e.getMessage(), e);
+            }
+        }
+    }
+
+    private void testIPRWLock(CuratorFramework curatorFramework, InterProcessReadWriteLock lock, String path) {
+        try {
+            lock.writeLock().acquire(10, TimeUnit.SECONDS);
+        } catch (Exception e1) {
+            try {
+                curatorFramework.delete().deletingChildrenIfNeeded().forPath(path);
+                curatorFramework.create().creatingParentContainersIfNeeded().withMode(CreateMode.PERSISTENT)
+                        .forPath(path);
+            } catch (Exception e2) {
+                LOG.info(e2.getMessage(), e2);
+            }
+        } finally {
+            try {
+                lock.writeLock().release();
+            } catch (Exception e3) {
+                LOG.error(e3.getMessage(), e3);
+            }
+        }
+    }
+
+    protected boolean shouldCache(String metricName) {
+
+        if (StringUtils.isBlank(metricName)) {
+            return false;
+        } else {
+            balancerLock.readLock().lock();
+            try {
+                nonCachedMetricsLocalLock.readLock().lock();
+                try {
+                    if (nonCachedMetrics.contains(metricName)) {
+                        return false;
+                    }
+                } finally {
+                    nonCachedMetricsLocalLock.readLock().unlock();
+                }
+                if (metricToHostMap.containsKey(metricName)) {
+                    return true;
+                }
+            } finally {
+                balancerLock.readLock().unlock();
+            }
+
+            nonCachedMetricsLocalLock.writeLock().lock();
+            try {
+                for (String r : nonCachedMetrics) {
+                    if (metricName.matches(r)) {
+                        LOG.debug("Adding {} to list of non-cached metrics", metricName);
+                        addNonCachedMetrics(Collections.singleton(metricName));
+                        return false;
+                    }
+                }
+            } finally {
+                nonCachedMetricsLocalLock.writeLock().unlock();
+            }
+            return true;
+        }
+    }
+
+    @Override
+    public TimelyBalancedHost getHostPortKeyIngest(String metric) {
+
+        TimelyBalancedHost tbh = null;
+        balancerLock.readLock().lock();
+        boolean chooseMetricSpecificHost;
+        try {
+            chooseMetricSpecificHost = shouldCache(metric) ? true : false;
+            if (chooseMetricSpecificHost) {
+                ArrivalRate rate = metricMap.get(metric);
+                if (rate == null) {
+                    rate = new ArrivalRate(arrivalRateExecutor);
+                    if (!balancerLock.isWriteLockedByCurrentThread()) {
+                        balancerLock.readLock().unlock();
+                        balancerLock.writeLock().lock();
+                    }
+                    metricMap.put(metric, rate);
+                }
+                rate.arrived();
+            } else {
+                metric = null;
+            }
+
+            if (StringUtils.isBlank(metric)) {
+                tbh = getRoundRobinHost(null);
+            } else {
+                tbh = metricToHostMap.get(metric);
+                if (tbh == null) {
+                    tbh = getRoundRobinHost(null);
+                    if (!balancerLock.isWriteLockedByCurrentThread()) {
+                        balancerLock.readLock().unlock();
+                        balancerLock.writeLock().lock();
+                    }
+                    assignMetric(metric, tbh, ASSIGN_ROUND_ROBIN);
+                } else if (!tbh.isUp()) {
+                    TimelyBalancedHost oldTbh = tbh;
+                    tbh = getRoundRobinHost(oldTbh);
+                    LOG.debug("rebalancing from host that is down: reassigning metric {} from server {} to {}", metric,
+                            TimelyBalancedHost.toStringShort(oldTbh), TimelyBalancedHost.toStringShort(tbh));
+                    if (!balancerLock.isWriteLockedByCurrentThread()) {
+                        balancerLock.readLock().unlock();
+                        balancerLock.writeLock().lock();
+                    }
+                    assignMetric(metric, tbh, HOST_DOWN_ROUND_ROBIN);
+                }
+            }
+
+            // if all else fails
+            if (tbh == null || !tbh.isUp()) {
+                for (TimelyBalancedHost h : serverList) {
+                    if (h.isUp()) {
+                        tbh = h;
+                        break;
+                    }
+                }
+                if (tbh != null && StringUtils.isNotBlank(metric)) {
+                    if (!balancerLock.isWriteLockedByCurrentThread()) {
+                        balancerLock.readLock().unlock();
+                        balancerLock.writeLock().lock();
+                    }
+                    assignMetric(metric, tbh, ASSIGN_FALLBACK_SEQUENTIAL);
+                }
+            }
+        } finally {
+            if (balancerLock.isWriteLockedByCurrentThread()) {
+                balancerLock.writeLock().unlock();
+            } else {
+                balancerLock.readLock().unlock();
+            }
+        }
+        if (tbh != null && chooseMetricSpecificHost) {
+            tbh.arrived();
+        }
+        return tbh;
+    }
+
+    @Override
+    public TimelyBalancedHost getHostPortKey(String metric) {
+        TimelyBalancedHost tbh = null;
+
+        balancerLock.readLock().lock();
+        try {
+            boolean chooseMetricSpecificHost = shouldCache(metric) ? true : false;
+            if (chooseMetricSpecificHost) {
+                tbh = metricToHostMap.get(metric);
+            } else {
+                metric = null;
+            }
+
+            if (tbh == null) {
+                tbh = getRoundRobinHost(null);
+                if (!balancerLock.isWriteLockedByCurrentThread()) {
+                    balancerLock.readLock().unlock();
+                    balancerLock.writeLock().lock();
+                }
+                assignMetric(metric, tbh, ASSIGN_ROUND_ROBIN);
+            } else if (!tbh.isUp()) {
+                TimelyBalancedHost oldTbh = tbh;
+                tbh = getRoundRobinHost(oldTbh);
+                LOG.debug("rebalancing from host that is down: reassigning metric {} from server {} to {}", metric,
+                        TimelyBalancedHost.toStringShort(oldTbh), TimelyBalancedHost.toStringShort(tbh));
+                if (!balancerLock.isWriteLockedByCurrentThread()) {
+                    balancerLock.readLock().unlock();
+                    balancerLock.writeLock().lock();
+                }
+                assignMetric(metric, tbh, HOST_DOWN_ROUND_ROBIN);
+            }
+
+            // if all else fails
+            if (tbh == null || !tbh.isUp()) {
+                for (TimelyBalancedHost h : serverList) {
+                    if (h.isUp()) {
+                        tbh = h;
+                        break;
+                    }
+                }
+                if (tbh != null && StringUtils.isNotBlank(metric)) {
+                    if (!balancerLock.isWriteLockedByCurrentThread()) {
+                        balancerLock.readLock().unlock();
+                        balancerLock.writeLock().lock();
+                    }
+                    assignMetric(metric, tbh, ASSIGN_FALLBACK_SEQUENTIAL);
+                }
+            }
+        } finally {
+            if (balancerLock.isWriteLockedByCurrentThread()) {
+                balancerLock.writeLock().unlock();
+            } else {
+                balancerLock.readLock().unlock();
+            }
+        }
+        return tbh;
+    }
+
+    protected TimelyBalancedHost findHost(String host, int tcpPort) {
+        TimelyBalancedHost tbh = null;
+        for (TimelyBalancedHost h : serverList) {
+            if (h.getHost().equals(host) && h.getTcpPort() == tcpPort) {
+                tbh = h;
+                break;
+            }
+        }
+        return tbh;
+    }
+
+    private void assignMetric(String metric, TimelyBalancedHost tbh, MetricAssignedEvent.Reason reason) {
+        if (isLeader.get()) {
+            if (StringUtils.isNotBlank(metric) && tbh != null) {
+                balancerLock.writeLock().lock();
+                try {
+                    metricAssignedEvent(metric, metricToHostMap.get(metric), tbh, reason);
+                    metricToHostMap.put(metric, tbh);
+                    assignmentsLastUpdatedLocal.set(System.currentTimeMillis());
+                } finally {
+                    balancerLock.writeLock().unlock();
+                }
+            } else {
+                unassignedMetrics.add(metric);
+                // Exception e = new IllegalStateException("Bad assignment metric:" + metric + "
+                // host:" + tbh);
+                LOG.warn("Bad assignment metric:" + metric + " host:" + tbh);
+            }
+        }
+    }
+
+    public void registerCallback(MetricAssignedCallback callback) {
+        this.metricAssignedCallbacks.add(callback);
+    }
+
+    public void registerCallback(MetricBalanceCallback callback) {
+        this.metricBalanceCallbacks.add(callback);
+    }
+
+    public void registerCallback(MetricHostCallback callback) {
+        this.metricHostCallbacks.add(callback);
+    }
+
+    protected void metricAssignedEvent(String metric, TimelyBalancedHost losing, TimelyBalancedHost gaining,
+            MetricAssignedEvent.Reason reason) {
+        if (!metricAssignedCallbacks.isEmpty()) {
+            MetricAssignedEvent event = new MetricAssignedEvent(metric, losing, gaining, reason);
+            for (MetricAssignedCallback callback : metricAssignedCallbacks) {
+                callback.onEvent(event);
+            }
+        }
+    }
+
+    protected void metricBalanceEvent(MetricBalanceEvent.ProgressType progressType,
+            BalancedMetricResolver.BalanceType balanceType, long numReassigned) {
+        if (!metricBalanceCallbacks.isEmpty()) {
+            MetricBalanceEvent event = new MetricBalanceEvent(progressType, balanceType, numReassigned);
+            for (MetricBalanceCallback callback : metricBalanceCallbacks) {
+                callback.onEvent(event);
+            }
+        }
+    }
+
+    protected void metricHostEvent(TimelyBalancedHost host, MetricHostEvent.ActionType actionType) {
+        if (!metricHostCallbacks.isEmpty()) {
+            MetricHostEvent event = new MetricHostEvent(host, actionType);
+            for (MetricHostCallback callback : metricHostCallbacks) {
+                callback.onEvent(event);
+            }
+        }
+    }
+
+    protected void writeAssignments(Map<String, TimelyBalancedHost> metricToHostMap) {
+        assignmentPerister.writeAssignments(metricToHostMap);
+    }
+
+    @Override
+    public void stop() {
+
+        this.assignmentExecutor.shutdown();
+        try {
+            this.assignmentExecutor.awaitTermination(5, TimeUnit.SECONDS);
+        } catch (InterruptedException e) {
+
+        } finally {
+            if (!this.assignmentExecutor.isTerminated()) {
+                this.assignmentExecutor.shutdownNow();
+            }
+        }
+
+        this.arrivalRateExecutor.shutdown();
+        try {
+            this.arrivalRateExecutor.awaitTermination(5, TimeUnit.SECONDS);
+        } catch (InterruptedException e) {
+
+        } finally {
+            if (!this.arrivalRateExecutor.isTerminated()) {
+                this.arrivalRateExecutor.shutdownNow();
+            }
+        }
+
+        try {
+            this.healthChecker.close();
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        }
+    }
+}

balancer/src/main/java/timely/balancer/resolver/MetricAssignmentPerister.java

@@ -0,0 +1,320 @@
+package timely.balancer.resolver;
+
+import static timely.balancer.Balancer.ASSIGNMENTS_LAST_UPDATED_PATH;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileNotFoundException;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.nio.charset.Charset;
+import java.util.Date;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+
+import com.csvreader.CsvReader;
+import com.csvreader.CsvWriter;
+import org.apache.commons.lang.StringUtils;
+import org.apache.curator.framework.CuratorFramework;
+import org.apache.curator.framework.recipes.atomic.DistributedAtomicLong;
+import org.apache.curator.framework.recipes.locks.InterProcessReadWriteLock;
+import org.apache.curator.retry.RetryForever;
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.fs.FileSystem;
+import org.apache.hadoop.fs.Path;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.resolver.eventing.MetricAssignedEvent;
+
+public class MetricAssignmentPerister {
+
+    private final Logger LOG = LoggerFactory.getLogger(getClass());
+
+    private enum PeristerType {
+        HDFS, FILE
+    }
+
+    // passed in through constructor
+    BalancedMetricResolver balancedMetricResolver;
+    private BalancerConfiguration balancerConfig;
+    private Map<String, TimelyBalancedHost> metricToHostMap;
+    private Set<String> nonCachedMetrics;
+    private InterProcessReadWriteLock assignmentsIPRWLock;
+    private ReentrantReadWriteLock nonCachedMetricsLocalLock;
+    private ReentrantReadWriteLock balancerLock;
+    private AtomicLong assignmentsLastUpdatedLocal;
+
+    // local
+    private DistributedAtomicLong assignmentsLastUpdatedInHdfs;
+
+    public MetricAssignmentPerister(BalancedMetricResolver balancedMetricResolver, BalancerConfiguration balancerConfig,
+            Map<String, TimelyBalancedHost> metricToHostMap, Set<String> nonCachedMetrics,
+            CuratorFramework curatorFramework, InterProcessReadWriteLock assignmentsIPRWLock,
+            ReentrantReadWriteLock nonCachedMetricsLocalLock, AtomicLong assignmentsLastUpdatedLocal,
+            ReentrantReadWriteLock balancerLock) {
+
+        this.balancedMetricResolver = balancedMetricResolver;
+        this.balancerConfig = balancerConfig;
+        this.metricToHostMap = metricToHostMap;
+        this.nonCachedMetrics = nonCachedMetrics;
+        this.assignmentsIPRWLock = assignmentsIPRWLock;
+        this.nonCachedMetricsLocalLock = nonCachedMetricsLocalLock;
+        this.assignmentsLastUpdatedLocal = assignmentsLastUpdatedLocal;
+        this.balancerLock = balancerLock;
+        assignmentsLastUpdatedInHdfs = new DistributedAtomicLong(curatorFramework, ASSIGNMENTS_LAST_UPDATED_PATH,
+                new RetryForever(1000));
+    }
+
+    public long getAssignmentsLastUpdatedByLeader() throws Exception {
+        return assignmentsLastUpdatedInHdfs.get().postValue();
+    }
+
+    public void readAssignments(boolean checkIfNecessary) {
+
+        try {
+            long lastLocalUpdate = assignmentsLastUpdatedLocal.get();
+            long lastHdfsUpdate = assignmentsLastUpdatedInHdfs.get().postValue();
+            if (checkIfNecessary) {
+                if (lastHdfsUpdate <= lastLocalUpdate) {
+                    LOG.debug("Not reading assignments from storage lastStorageUpdate ({}) <= lastLocalUpdate ({})",
+                            new Date(lastHdfsUpdate), new Date(lastLocalUpdate));
+                    return;
+                }
+            }
+            LOG.debug("Reading assignments from storage lastStorageUpdate ({}) > lastLocalUpdate ({})",
+                    new Date(lastHdfsUpdate), new Date(lastLocalUpdate));
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        }
+
+        // proceed with reading from storage
+
+        try (InputStream inputStream = getInputStream(balancerConfig)) {
+            boolean acquired = false;
+            while (!acquired) {
+                acquired = assignmentsIPRWLock.readLock().acquire(60, TimeUnit.SECONDS);
+            }
+            balancerLock.writeLock().lock();
+            // get potential new list from implementation
+            Map<String, TimelyBalancedHost> assignedMetricToHostMap = readFromStream(inputStream);
+            metricToHostMap.clear();
+            for (Map.Entry<String, TimelyBalancedHost> e : assignedMetricToHostMap.entrySet()) {
+                if (StringUtils.isNotBlank(e.getKey()) && e.getValue() != null) {
+                    if (balancedMetricResolver.shouldCache(e.getKey())) {
+                        balancedMetricResolver.metricAssignedEvent(e.getKey(), null, e.getValue(),
+                                MetricAssignedEvent.Reason.ASSIGN_FILE);
+                        metricToHostMap.put(e.getKey(), e.getValue());
+                    }
+                } else {
+                    Exception e1 = new IllegalStateException(
+                            "Bad assignment metric:" + e.getKey() + " host:" + e.getValue());
+                    LOG.warn(e1.getMessage(), e1);
+                }
+            }
+            nonCachedMetricsLocalLock.readLock().lock();
+            try {
+                Iterator<Map.Entry<String, TimelyBalancedHost>> itr = metricToHostMap.entrySet().iterator();
+                while (itr.hasNext()) {
+                    Map.Entry<String, TimelyBalancedHost> e = itr.next();
+                    if (nonCachedMetrics.contains(e.getKey())) {
+                        itr.remove();
+                    }
+                }
+            } finally {
+                nonCachedMetricsLocalLock.readLock().unlock();
+            }
+            assignmentsLastUpdatedLocal.set(assignmentsLastUpdatedInHdfs.get().postValue());
+            LOG.info("Read {} assignments from storage lastStorageUpdate = lastLocalUpdate ({})",
+                    metricToHostMap.size(), new Date(assignmentsLastUpdatedLocal.get()));
+        } catch (FileNotFoundException e) {
+            createAssignmentFile();
+            metricToHostMap.clear();
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        } finally {
+            balancerLock.writeLock().unlock();
+            try {
+                assignmentsIPRWLock.readLock().release();
+            } catch (Exception e) {
+                LOG.error(e.getMessage(), e);
+            }
+        }
+    }
+
+    public void writeAssignments() {
+        writeAssignments(metricToHostMap);
+    }
+
+    protected void writeAssignments(Map<String, TimelyBalancedHost> metricToHostMap) {
+
+        try {
+            boolean acquired = false;
+            while (!acquired) {
+                acquired = assignmentsIPRWLock.writeLock().acquire(60, TimeUnit.SECONDS);
+            }
+            balancerLock.readLock().lock();
+            nonCachedMetricsLocalLock.readLock().lock();
+            try (OutputStream outputStream = getOutputStream(balancerConfig)) {
+                if (!metricToHostMap.isEmpty()) {
+                    writeToStream(outputStream);
+                    long now = System.currentTimeMillis();
+                    assignmentsLastUpdatedLocal.set(now);
+                    assignmentsLastUpdatedInHdfs.trySet(now);
+                    if (!assignmentsLastUpdatedInHdfs.get().succeeded()) {
+                        assignmentsLastUpdatedInHdfs.forceSet(now);
+                    }
+                    LOG.debug("Wrote {} assignments to storage lastStorageUpdate = lastLocalUpdate ({})",
+                            metricToHostMap.size(), new Date(assignmentsLastUpdatedLocal.get()));
+                }
+            } finally {
+                nonCachedMetricsLocalLock.readLock().unlock();
+                balancerLock.readLock().unlock();
+            }
+        } catch (Exception e) {
+            LOG.error(e.getMessage(), e);
+        } finally {
+            try {
+                assignmentsIPRWLock.writeLock().release();
+            } catch (Exception e) {
+                LOG.error(e.getMessage(), e);
+            }
+        }
+    }
+
+    public Map<String, TimelyBalancedHost> readFromStream(InputStream inputStream) throws IOException {
+        Map<String, TimelyBalancedHost> assignedMetricToHostMap = new TreeMap<>();
+        try {
+            CsvReader reader = new CsvReader(inputStream, ',', Charset.forName("UTF-8"));
+            reader.setUseTextQualifier(false);
+
+            // skip the headers
+            boolean success = true;
+            success = reader.readHeaders();
+
+            while (success) {
+                success = reader.readRecord();
+                String[] nextLine = reader.getValues();
+                if (nextLine.length >= 3) {
+                    String metric = nextLine[0];
+                    String host = nextLine[1];
+                    int tcpPort = Integer.parseInt(nextLine[2]);
+                    TimelyBalancedHost tbh = balancedMetricResolver.findHost(host, tcpPort);
+                    if (tbh == null) {
+                        tbh = balancedMetricResolver.getRoundRobinHost(null);
+                    } else {
+                        LOG.trace("Found assigment: {} to {}:{}", metric, host, tcpPort);
+                    }
+                    assignedMetricToHostMap.put(metric, tbh);
+                }
+            }
+        } catch (IOException e) {
+            LOG.error(e.getMessage(), e);
+            throw e;
+        }
+        return assignedMetricToHostMap;
+    }
+
+    private void writeToStream(OutputStream outputStream) throws IOException {
+
+        CsvWriter writer = null;
+        try {
+            writer = new CsvWriter(outputStream, ',', Charset.forName("UTF-8"));
+            writer.setUseTextQualifier(false);
+            writer.write("metric");
+            writer.write("host");
+            writer.write("tcpPort");
+            writer.endRecord();
+            for (Map.Entry<String, TimelyBalancedHost> e : metricToHostMap.entrySet()) {
+                if (!nonCachedMetrics.contains(e.getKey())) {
+                    writer.write(e.getKey());
+                    writer.write(e.getValue().getHost());
+                    writer.write(Integer.toString(e.getValue().getTcpPort()));
+                    writer.endRecord();
+                    LOG.trace("Saving assigment: {} to {}:{}", e.getKey(), e.getValue().getHost(),
+                            e.getValue().getTcpPort());
+                }
+            }
+        } finally {
+            if (writer != null) {
+                writer.close();
+            }
+        }
+    }
+
+    public void createAssignmentFile() {
+        LOG.info("Creating assignment file: " + balancerConfig.getAssignmentFile());
+        PeristerType peristerType = PeristerType.valueOf(balancerConfig.getMetricAssignmentPersisterType());
+        switch (peristerType) {
+            case HDFS:
+                try {
+                    Configuration configuration = new Configuration();
+                    FileSystem fs = FileSystem.get(configuration);
+                    Path assignmentFile = new Path(balancerConfig.getAssignmentFile());
+                    fs.create(assignmentFile);
+                } catch (Exception e) {
+                    LOG.error(e.getMessage(), e);
+                }
+                break;
+            case FILE:
+                try {
+                    File assignmentFile = new File(balancerConfig.getAssignmentFile());
+                    String parentPath = assignmentFile.getParent();
+                    File directory = new File(parentPath);
+                    if (!directory.exists()) {
+
+                        directory.mkdirs();
+                    }
+                    if (!assignmentFile.exists()) {
+                        assignmentFile.createNewFile();
+                    }
+                } catch (Exception e) {
+                    LOG.error(e.getMessage(), e);
+                }
+                break;
+        }
+    }
+
+    public InputStream getInputStream(BalancerConfiguration balancerConfiguration) throws Exception {
+        PeristerType peristerType = PeristerType.valueOf(balancerConfiguration.getMetricAssignmentPersisterType());
+        switch (peristerType) {
+            case HDFS:
+                Configuration configuration = new Configuration();
+                FileSystem fs = FileSystem.get(configuration);
+                Path assignmentFile = new Path(balancerConfiguration.getAssignmentFile());
+                return fs.open(assignmentFile);
+            case FILE:
+                return new FileInputStream(new File(balancerConfiguration.getAssignmentFile()));
+            default:
+                throw new IllegalArgumentException(
+                        "Unknown metricPersisterType " + balancerConfiguration.getMetricAssignmentPersisterType());
+        }
+    }
+
+    public OutputStream getOutputStream(BalancerConfiguration balancerConfiguration) throws IOException {
+        PeristerType peristerType = PeristerType.valueOf(balancerConfiguration.getMetricAssignmentPersisterType());
+        switch (peristerType) {
+            case HDFS:
+                Configuration configuration = new Configuration();
+                FileSystem fs = FileSystem.get(configuration);
+                Path assignmentFile = new Path(balancerConfiguration.getAssignmentFile());
+                if (!fs.exists(assignmentFile.getParent())) {
+                    fs.mkdirs(assignmentFile.getParent());
+                }
+                return fs.create(assignmentFile, true);
+            case FILE:
+                return new FileOutputStream(new File(balancerConfiguration.getAssignmentFile()));
+            default:
+                throw new IllegalArgumentException(
+                        "Unknown metricPersisterType " + balancerConfiguration.getMetricAssignmentPersisterType());
+        }
+    }
+}

balancer/src/main/java/timely/balancer/resolver/MetricResolver.java

@@ -0,0 +1,15 @@
+package timely.balancer.resolver;
+
+import timely.balancer.connection.TimelyBalancedHost;
+
+public interface MetricResolver {
+
+    public TimelyBalancedHost getHostPortKeyIngest(String metric);
+
+    public TimelyBalancedHost getHostPortKey(String metric);
+
+    public void start();
+
+    public void stop();
+
+}

balancer/src/main/java/timely/balancer/resolver/eventing/MetricAssignedCallback.java

@@ -0,0 +1,7 @@
+package timely.balancer.resolver.eventing;
+
+public abstract class MetricAssignedCallback {
+
+    public abstract void onEvent(MetricAssignedEvent event);
+
+}

balancer/src/main/java/timely/balancer/resolver/eventing/MetricAssignedEvent.java

@@ -0,0 +1,39 @@
+package timely.balancer.resolver.eventing;
+
+import timely.balancer.connection.TimelyBalancedHost;
+
+public class MetricAssignedEvent {
+
+    public enum Reason {
+        ASSIGN_ROUND_ROBIN, HOST_DOWN_ROUND_ROBIN, ASSIGN_FALLBACK_SEQUENTIAL, HOST_REMOVED, REBALANCE, ASSIGN_FILE
+    }
+
+    private final String metric;
+    private final TimelyBalancedHost losingHost;
+    private final TimelyBalancedHost gainingHost;
+    private final Reason reason;
+
+    public MetricAssignedEvent(String metric, TimelyBalancedHost losingHost, TimelyBalancedHost gainingHost,
+            Reason reason) {
+        this.metric = metric;
+        this.losingHost = losingHost;
+        this.gainingHost = gainingHost;
+        this.reason = reason;
+    }
+
+    public String getMetric() {
+        return metric;
+    }
+
+    public TimelyBalancedHost getLosingHost() {
+        return losingHost;
+    }
+
+    public TimelyBalancedHost getGainingHost() {
+        return gainingHost;
+    }
+
+    public Reason getReason() {
+        return reason;
+    }
+}

balancer/src/main/java/timely/balancer/resolver/eventing/MetricBalanceCallback.java

@@ -0,0 +1,7 @@
+package timely.balancer.resolver.eventing;
+
+public abstract class MetricBalanceCallback {
+
+    public abstract void onEvent(MetricBalanceEvent event);
+
+}

balancer/src/main/java/timely/balancer/resolver/eventing/MetricBalanceEvent.java

@@ -0,0 +1,33 @@
+package timely.balancer.resolver.eventing;
+
+import timely.balancer.resolver.BalancedMetricResolver;
+
+public class MetricBalanceEvent {
+
+    public enum ProgressType {
+        BEGIN, BALANCER_LOCK_ACQUIRED, END
+    }
+
+    private final ProgressType progressType;
+    private final BalancedMetricResolver.BalanceType balanceType;
+    private final Long numRessigned;
+
+    public MetricBalanceEvent(ProgressType progressType, BalancedMetricResolver.BalanceType balanceType,
+            long numReassigned) {
+        this.progressType = progressType;
+        this.balanceType = balanceType;
+        this.numRessigned = numReassigned;
+    }
+
+    public BalancedMetricResolver.BalanceType getBalanceType() {
+        return balanceType;
+    }
+
+    public ProgressType getProgressType() {
+        return progressType;
+    }
+
+    public Long getNumRessigned() {
+        return numRessigned;
+    }
+}

balancer/src/main/java/timely/balancer/resolver/eventing/MetricHostCallback.java

@@ -0,0 +1,7 @@
+package timely.balancer.resolver.eventing;
+
+public abstract class MetricHostCallback {
+
+    public abstract void onEvent(MetricHostEvent event);
+
+}

balancer/src/main/java/timely/balancer/resolver/eventing/MetricHostEvent.java

@@ -0,0 +1,26 @@
+package timely.balancer.resolver.eventing;
+
+import timely.balancer.connection.TimelyBalancedHost;
+
+public class MetricHostEvent {
+
+    public enum ActionType {
+        ADDED, REMOVED, SUCCESS, FAILURE
+    }
+
+    private final TimelyBalancedHost timelyBalancedHost;
+    private final ActionType actionType;
+
+    public MetricHostEvent(TimelyBalancedHost timelyBalancedHost, ActionType actionType) {
+        this.timelyBalancedHost = timelyBalancedHost;
+        this.actionType = actionType;
+    }
+
+    public TimelyBalancedHost getTimelyBalancedHost() {
+        return timelyBalancedHost;
+    }
+
+    public ActionType getActionType() {
+        return actionType;
+    }
+}

balancer/src/main/resources/fb/compile_fb.sh

@@ -0,0 +1,2 @@
+cd src/main/generated-java
+flatc --java ../resources/fb/metric.fbs

balancer/src/main/resources/fb/metric.fbs

@@ -0,0 +1,21 @@
+namespace timely.api.flatbuffer;
+
+file_identifier "TMFB";
+
+table Tag {
+  key:string;
+  value:string;
+}
+
+table Metric {
+  name:string;
+  timestamp:long;
+  value:double;
+  tags:[Tag];
+}
+
+table Metrics {
+  metrics:[Metric];
+}
+
+root_type Metrics;

balancer/src/main/spotbugs/excludes.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<FindBugsFilter>
+  <Match>
+    <Class name="timely.balancer.Balancer" />
+    <Method name="shutdown" />
+    <Bug pattern="UC_USELESS_OBJECT" />
+  </Match>
+  <Match>
+    <Class name="timely.balancer.netty.http.HttpRelayHandler$MyByteArrayOutputStream" />
+    <Method name="getBuf" />
+    <Bug pattern="EI_EXPOSE_REP" />
+  </Match>
+  <Match>
+    <Class name="timely.balancer.resolver.MetricAssignmentPerister" />
+    <Method name="createAssignmentFile" />
+    <Bug pattern="RV_RETURN_VALUE_IGNORED_BAD_PRACTICE" />
+  </Match>
+</FindBugsFilter>

balancer/src/test/java/timely/balancer/resolver/ServiceRegistry.java

@@ -0,0 +1,76 @@
+package timely.balancer.resolver;
+
+import static timely.Server.SERVICE_DISCOVERY_PATH;
+
+import org.apache.curator.framework.CuratorFramework;
+import org.apache.curator.x.discovery.ServiceDiscovery;
+import org.apache.curator.x.discovery.ServiceDiscoveryBuilder;
+import org.apache.curator.x.discovery.ServiceInstance;
+import org.apache.curator.x.discovery.ServiceInstanceBuilder;
+import org.apache.zookeeper.data.Stat;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.ServerDetails;
+import timely.balancer.connection.TimelyBalancedHost;
+
+public class ServiceRegistry {
+
+    private static final Logger LOG = LoggerFactory.getLogger(ServiceRegistry.class);
+
+    public static void registerService(CuratorFramework curatorFramework, TimelyBalancedHost tbh) {
+        try {
+            try {
+                Stat stat = curatorFramework.checkExists().forPath(SERVICE_DISCOVERY_PATH);
+                if (stat == null) {
+                    curatorFramework.create().creatingParentContainersIfNeeded().forPath(SERVICE_DISCOVERY_PATH);
+                }
+            } catch (Exception e) {
+                LOG.error(e.getMessage());
+            }
+
+            ServiceInstance<ServerDetails> serviceInstance = serviceInstance(tbh);
+            ServiceDiscovery<ServerDetails> discovery = ServiceDiscoveryBuilder.builder(ServerDetails.class)
+                    .client(curatorFramework).basePath(SERVICE_DISCOVERY_PATH).build();
+            discovery.start();
+            discovery.registerService(serviceInstance);
+        } catch (Exception e) {
+            LOG.error(e.getMessage());
+        }
+    }
+
+    public static void unregisterService(CuratorFramework curatorFramework, TimelyBalancedHost tbh) {
+        try {
+            try {
+                Stat stat = curatorFramework.checkExists().forPath(SERVICE_DISCOVERY_PATH);
+                if (stat == null) {
+                    curatorFramework.create().creatingParentContainersIfNeeded().forPath(SERVICE_DISCOVERY_PATH);
+                }
+            } catch (Exception e) {
+                LOG.error(e.getMessage());
+            }
+
+            ServiceInstance<ServerDetails> serviceInstance = serviceInstance(tbh);
+            ServiceDiscovery<ServerDetails> discovery = ServiceDiscoveryBuilder.builder(ServerDetails.class)
+                    .client(curatorFramework).basePath(SERVICE_DISCOVERY_PATH).build();
+            discovery.start();
+            discovery.unregisterService(serviceInstance);
+        } catch (Exception e) {
+            LOG.error(e.getMessage());
+        }
+    }
+
+    private static ServiceInstance<ServerDetails> serviceInstance(TimelyBalancedHost config) throws Exception {
+        ServerDetails serverDetails = new ServerDetails();
+        serverDetails.setHost(config.getHost());
+        serverDetails.setTcpPort(config.getTcpPort());
+        serverDetails.setHttpPort(config.getHttpPort());
+        serverDetails.setWsPort(config.getWsPort());
+        serverDetails.setUdpPort(config.getUdpPort());
+
+        ServiceInstanceBuilder<ServerDetails> builder = ServiceInstance.builder();
+        String serviceName = config.getHost() + ":" + config.getTcpPort();
+        ServiceInstance<ServerDetails> serviceInstance = builder.id(serviceName).name("timely-server")
+                .address(config.getHost()).port(config.getTcpPort()).payload(serverDetails).build();
+        return serviceInstance;
+    }
+}

balancer/src/test/java/timely/balancer/resolver/TestBalancedMetricResolver.java

@@ -0,0 +1,270 @@
+package timely.balancer.resolver;
+
+import java.io.File;
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.text.SimpleDateFormat;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Properties;
+import java.util.Random;
+import java.util.UUID;
+
+import org.apache.curator.framework.CuratorFramework;
+import org.apache.curator.framework.CuratorFrameworkFactory;
+import org.apache.curator.retry.RetryNTimes;
+import org.apache.zookeeper.server.ServerConfig;
+import org.apache.zookeeper.server.ZooKeeperServerMain;
+import org.apache.zookeeper.server.quorum.QuorumPeerConfig;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.util.SocketUtils;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.resolver.eventing.MetricAssignedCallback;
+import timely.balancer.resolver.eventing.MetricAssignedEvent;
+import timely.balancer.resolver.eventing.MetricBalanceCallback;
+import timely.balancer.resolver.eventing.MetricBalanceEvent;
+import timely.balancer.resolver.eventing.MetricHostCallback;
+import timely.balancer.resolver.eventing.MetricHostEvent;
+
+public class TestBalancedMetricResolver {
+
+    private final Logger LOG = LoggerFactory.getLogger(getClass());
+    private CuratorFramework curatorFramework;
+    private SimpleDateFormat sdf = new SimpleDateFormat("yyyyMMdd HHmmss.SSS");
+    private Random r = new Random(System.currentTimeMillis());
+    private List<TimelyBalancedHost> timelyHosts;
+    private Map<MetricAssignedEvent, Integer> metricBalanceEventCounter = new HashMap<>();
+
+    @Before
+    public void startup() {
+        QuorumPeerConfig currentConfig = createZookeeper();
+        InetSocketAddress address = currentConfig.getClientPortAddress();
+        String zkServer = address.getHostName() + ":" + address.getPort();
+        curatorFramework = CuratorFrameworkFactory.newClient(zkServer, 1000, 5000, new RetryNTimes(2, 50));
+        curatorFramework.start();
+        timelyHosts = new ArrayList<>();
+    }
+
+    @After
+    public void shutdown() {
+        curatorFramework.close();
+    }
+
+    private QuorumPeerConfig createZookeeper() {
+        Properties startupProperties = new Properties();
+        File file = new File(System.getProperty("java.io.tmpdir") + File.separator + UUID.randomUUID());
+        file.deleteOnExit();
+        startupProperties.setProperty("dataDir", file.getAbsolutePath());
+        startupProperties.setProperty("clientPort", String.valueOf(SocketUtils.findAvailableTcpPort(3000, 4000)));
+        QuorumPeerConfig quorumConfiguration = new QuorumPeerConfig();
+
+        try {
+            quorumConfiguration.parseProperties(startupProperties);
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+
+        ZooKeeperServerMain zooKeeperServer = new ZooKeeperServerMain();
+        final ServerConfig configuration = new ServerConfig();
+        configuration.readFrom(quorumConfiguration);
+
+        new Thread() {
+
+            public void run() {
+                try {
+                    zooKeeperServer.runFromConfig(configuration);
+                } catch (IOException e) {
+                    LOG.error("ZooKeeper Failed", e);
+                }
+            }
+        }.start();
+
+        return quorumConfiguration;
+    }
+
+    private BalancerConfiguration getBalancerConfiguration() {
+        BalancerConfiguration balancerConfiguration = new BalancerConfiguration();
+        balancerConfiguration.setMetricAssignmentPersisterType("FILE");
+        File file = new File(System.getProperty("java.io.tmpdir") + File.separator + UUID.randomUUID());
+        file.deleteOnExit();
+        balancerConfiguration.setAssignmentFile(file.getAbsolutePath());
+        balancerConfiguration.setBalanceDelay(0);
+        balancerConfiguration.setBalancePeriod(1000);
+        balancerConfiguration.setPersistDelay(0);
+        balancerConfiguration.setPersistDelay(1000);
+        balancerConfiguration.setCheckServerHealthInterval(10);
+        return balancerConfiguration;
+    }
+
+    private void createTimelyHosts(BalancerConfiguration balancerConfiguration, int numHosts) {
+        for (int port = 1000, x = 0; x < numHosts; x++, port += 10) {
+            TimelyBalancedHost tbh = TimelyBalancedHost.of("localhost", port);
+            tbh.setBalancerConfig(balancerConfiguration);
+            timelyHosts.add(tbh);
+            ServiceRegistry.registerService(curatorFramework, tbh);
+        }
+    }
+
+    private void registerCallbacks(BalancedMetricResolver resolver) {
+        resolver.registerCallback(new MetricAssignedCallback() {
+
+            @Override
+            public void onEvent(MetricAssignedEvent event) {
+                LOG.debug(String.format("%s metric:%s lose:%s:%d gain:%s:%d reason:%s",
+                        event.getClass().getSimpleName(), event.getMetric(),
+                        event.getLosingHost() == null ? null : event.getLosingHost().getHost(),
+                        event.getLosingHost() == null ? null : event.getLosingHost().getTcpPort(),
+                        event.getGainingHost().getHost(), event.getGainingHost().getTcpPort(), event.getReason()));
+            }
+        });
+
+        resolver.registerCallback(new MetricHostCallback() {
+
+            @Override
+            public void onEvent(MetricHostEvent event) {
+                LOG.debug(String.format("%s host:%s:%d type:%s", event.getClass().getSimpleName(),
+                        event.getTimelyBalancedHost().getHost(), event.getTimelyBalancedHost().getTcpPort(),
+                        event.getActionType()));
+            }
+        });
+
+        resolver.registerCallback(new MetricBalanceCallback() {
+
+            @Override
+            public void onEvent(MetricBalanceEvent event) {
+                LOG.debug(String.format("%s type:%s progress:%s reassigned:%d", event.getClass().getSimpleName(),
+                        event.getBalanceType(), event.getProgressType(), event.getNumRessigned()));
+            }
+        });
+    }
+
+    private TimelyBalancedHost randomServerDown(TestHealthChecker healthChecker, int numHosts) {
+        TimelyBalancedHost tbh = timelyHosts.get(r.nextInt(numHosts));
+        LOG.debug("Marking server down:" + TimelyBalancedHost.toStringShort(tbh));
+        healthChecker.serverDown(tbh);
+        return tbh;
+    }
+
+    private TimelyBalancedHost randomServerToggle(TestHealthChecker healthChecker, int numHosts) {
+        TimelyBalancedHost tbh = timelyHosts.get(r.nextInt(numHosts));
+        LOG.debug("Marking server " + (tbh.isUp() ? "down:" : "up:") + TimelyBalancedHost.toStringShort(tbh));
+        healthChecker.serverToggle(tbh);
+        return tbh;
+    }
+
+    private TimelyBalancedHost randomServerUnregister(int numHosts) {
+        TimelyBalancedHost tbh = timelyHosts.get(r.nextInt(numHosts));
+        LOG.debug("Unregistering:" + TimelyBalancedHost.toStringShort(tbh));
+        ServiceRegistry.unregisterService(curatorFramework, tbh);
+        return tbh;
+    }
+
+    @Test
+    public void test1() {
+        LOG.debug("Configure test");
+        int numHosts = 10;
+        BalancerConfiguration balancerConfiguration = getBalancerConfiguration();
+        createTimelyHosts(balancerConfiguration, numHosts);
+        TestHealthChecker healthChecker = new TestHealthChecker(balancerConfiguration, timelyHosts);
+        BalancedMetricResolver balancedMetricResolver = new BalancedMetricResolver(curatorFramework,
+                balancerConfiguration, healthChecker);
+        registerCallbacks(balancedMetricResolver);
+        LOG.debug("Start balancedMetricResolver");
+        balancedMetricResolver.start();
+        long now = System.currentTimeMillis();
+        int numMetrics = 100;
+        for (int x = 0; x < numMetrics; x++) {
+            balancedMetricResolver.getHostPortKeyIngest(String.format("metric%03d", x));
+        }
+
+        LOG.debug("Begin monitoring");
+        long cycle = 0;
+        List<TimelyBalancedHost> serversUnregistered = new ArrayList<>();
+        while (System.currentTimeMillis() < now + 15000) {
+            try {
+                Thread.sleep(100);
+                for (int x = 0; x < 10000; x++) {
+                    int mNum = r.nextInt(numMetrics);
+                    balancedMetricResolver.getHostPortKeyIngest(String.format("metric%03d", mNum));
+                }
+                // if (cycle % 100 == 0) {
+                // randomServerDown(healthChecker, numHosts);
+                // }
+                // if (cycle % 2 == 0) {
+                // randomServerToggle(healthChecker, numHosts);
+                // }
+                if (cycle % 100 == 0) {
+                    serversUnregistered.add(randomServerUnregister(numHosts));
+                }
+                if (cycle % 500 == 0) {
+                    serversUnregistered.stream().forEach(tbh -> ServiceRegistry.registerService(curatorFramework, tbh));
+                    serversUnregistered.clear();
+                }
+
+            } catch (InterruptedException e) {
+
+            }
+            cycle++;
+        }
+        LOG.debug("Stop balancedMetricResolver");
+        balancedMetricResolver.stop();
+    }
+
+    @Test
+    public void test2() {
+        LOG.debug("Configure test");
+        int numHosts = 10;
+        BalancerConfiguration balancerConfiguration = getBalancerConfiguration();
+        createTimelyHosts(balancerConfiguration, numHosts);
+        TestHealthChecker healthChecker = new TestHealthChecker(balancerConfiguration, timelyHosts);
+        BalancedMetricResolver balancedMetricResolver = new BalancedMetricResolver(curatorFramework,
+                balancerConfiguration, healthChecker);
+        registerCallbacks(balancedMetricResolver);
+        LOG.debug("Start balancedMetricResolver");
+        balancedMetricResolver.start();
+        long now = System.currentTimeMillis();
+        int numMetrics = 100;
+        for (int x = 0; x < numMetrics; x++) {
+            balancedMetricResolver.getHostPortKeyIngest(String.format("metric%03d", x));
+        }
+
+        LOG.debug("Begin monitoring");
+        long cycle = 0;
+        List<TimelyBalancedHost> serversUnregistered = new ArrayList<>();
+        while (System.currentTimeMillis() < now + 15000) {
+            try {
+                Thread.sleep(100);
+                for (int x = 0; x < 10000; x++) {
+                    int mNum = r.nextInt(numMetrics);
+                    balancedMetricResolver.getHostPortKeyIngest(String.format("metric%03d", mNum));
+                }
+                // if (cycle % 100 == 0) {
+                // randomServerDown(healthChecker, numHosts);
+                // }
+                // if (cycle % 2 == 0) {
+                // randomServerToggle(healthChecker, numHosts);
+                // }
+                if (cycle % 100 == 0) {
+                    serversUnregistered.add(randomServerUnregister(numHosts));
+                }
+                if (cycle % 500 == 0) {
+                    serversUnregistered.stream().forEach(tbh -> ServiceRegistry.registerService(curatorFramework, tbh));
+                    serversUnregistered.clear();
+                }
+
+            } catch (InterruptedException e) {
+
+            }
+            cycle++;
+        }
+        LOG.debug("Stop balancedMetricResolver");
+        balancedMetricResolver.stop();
+    }
+}

balancer/src/test/java/timely/balancer/resolver/TestHealthChecker.java

@@ -0,0 +1,89 @@
+package timely.balancer.resolver;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.balancer.configuration.BalancerConfiguration;
+import timely.balancer.connection.TimelyBalancedHost;
+import timely.balancer.healthcheck.HealthChecker;
+import timely.balancer.healthcheck.TcpHealthChecker;
+
+public class TestHealthChecker implements HealthChecker {
+
+    private final Logger LOG = LoggerFactory.getLogger(TcpHealthChecker.class);
+    private List<TimelyBalancedHost> timelyHosts = new ArrayList<>();
+    private Map<TimelyBalancedHost, Boolean> serverUpMap = Collections.synchronizedMap(new HashMap<>());
+    private ScheduledExecutorService executorService = Executors.newScheduledThreadPool(1);
+
+    public TestHealthChecker(BalancerConfiguration config, List<TimelyBalancedHost> timelyHosts) {
+        setTimelyHosts(timelyHosts);
+        this.executorService.scheduleAtFixedRate(() -> {
+            synchronized (timelyHosts) {
+                for (TimelyBalancedHost h : timelyHosts) {
+                    try {
+                        if (TestHealthChecker.this.isServerHealthy(h)) {
+                            h.reportSuccess();
+                        } else {
+                            h.reportFailure();
+                        }
+                    } catch (Exception e) {
+                        LOG.error(e.getMessage(), e);
+                        h.reportFailure();
+                    }
+                }
+            }
+        }, 0, config.getCheckServerHealthInterval(), TimeUnit.MILLISECONDS);
+    }
+
+    @Override
+    public void setTimelyHosts(List<TimelyBalancedHost> timelyHosts) {
+        synchronized (timelyHosts) {
+            this.timelyHosts.clear();
+            this.timelyHosts.addAll(timelyHosts);
+            for (TimelyBalancedHost h : timelyHosts) {
+                serverUpMap.put(h, true);
+            }
+        }
+
+    }
+
+    public boolean isServerHealthy(TimelyBalancedHost h) {
+        return serverUpMap.get(h);
+    }
+
+    public void serverUp(TimelyBalancedHost h) {
+        serverUpMap.put(h, true);
+    }
+
+    public void serverDown(TimelyBalancedHost h) {
+        serverUpMap.put(h, false);
+    }
+
+    public void serverToggle(TimelyBalancedHost h) {
+        synchronized (serverUpMap) {
+            serverUpMap.put(h, !serverUpMap.get(h));
+        }
+    }
+
+    @Override
+    public void close() throws Exception {
+        this.executorService.shutdown();
+        try {
+            this.executorService.awaitTermination(5, TimeUnit.SECONDS);
+        } catch (InterruptedException e) {
+
+        } finally {
+            if (!this.executorService.isTerminated()) {
+                this.executorService.shutdownNow();
+            }
+        }
+    }
+}

balancer/src/test/resources/log4j2.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="WARN">
+  <Appenders>
+    <Console name="CONSOLE" target="SYSTEM_OUT">
+      <PatternLayout pattern="%d{yyyyMMdd HHmmss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
+    </Console>
+  </Appenders>
+  <Loggers>
+    <Logger name="org.apache.accumulo.core.client.impl.ThriftTransportPool" level="OFF" additivity="false" />
+    <Logger name="org.apache.accumulo.fate.zookeeper.ZooCache" level="OFF" additivity="false" />
+    <Logger name="org.apache.zookeeper" level="OFF" additivity="false" />
+    <Logger name="timely.balancer.resolver" level="TRACE" additivity="true" />
+    <Logger name="timely.balancer.resolver.TestBalancedMetricResolver" level="DEBUG" additivity="true" />
+    <Root level="ERROR">
+      <AppenderRef ref="CONSOLE"/>
+    </Root>
+  </Loggers>
+</Configuration>

client/.gitignore

@@ -0,0 +1 @@
+/target/

client/pom.xml

@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>timely</groupId>
+    <artifactId>timely</artifactId>
+    <version>1.2.8-SNAPSHOT</version>
+  </parent>
+  <artifactId>timely-client</artifactId>
+  <properties>
+    <!-- PEP 440 compliant version gets substituted into src/main/python/template/setup.py -->
+    <!-- use .dev0 instead of -SNAPSHOT -->
+    <python.client.version>1.2.8.dev0</python.client.version>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-annotations</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-core</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.datatype</groupId>
+      <artifactId>jackson-datatype-jdk8</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.google.guava</groupId>
+      <artifactId>guava</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-lang3</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.httpcomponents</groupId>
+      <artifactId>httpclient</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.glassfish.tyrus</groupId>
+      <artifactId>tyrus-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.glassfish.tyrus</groupId>
+      <artifactId>tyrus-container-grizzly-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-api</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-core</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-slf4j-impl</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>timely</groupId>
+      <artifactId>timely-common</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>filter-setup</id>
+            <goals>
+              <goal>copy-resources</goal>
+            </goals>
+            <phase>process-resources</phase>
+            <configuration>
+              <outputDirectory>${project.basedir}/src/main/python</outputDirectory>
+              <resources>
+                <resource>
+                  <directory>${project.basedir}/src/main/python/template</directory>
+                  <includes>
+                    <include>setup.py</include>
+                  </includes>
+                  <filtering>true</filtering>
+                </resource>
+              </resources>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+  <profiles>
+    <profile>
+      <id>python</id>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.codehaus.mojo</groupId>
+            <artifactId>exec-maven-plugin</artifactId>
+            <executions>
+              <execution>
+                <id>python-dist</id>
+                <goals>
+                  <goal>exec</goal>
+                </goals>
+                <phase>package</phase>
+                <configuration>
+                  <executable>python</executable>
+                  <workingDirectory>${project.basedir}/src/main/python</workingDirectory>
+                  <commandlineArgs>setup.py sdist --dist-dir ${project.build.directory}</commandlineArgs>
+                </configuration>
+              </execution>
+              <execution>
+                <id>python-clean</id>
+                <goals>
+                  <goal>exec</goal>
+                </goals>
+                <phase>package</phase>
+                <configuration>
+                  <executable>rm</executable>
+                  <workingDirectory>${project.basedir}/src/main/python</workingDirectory>
+                  <commandlineArgs>-rf timely.egg-info setup.py</commandlineArgs>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
+</project>

client/src/main/java/timely/api/AddSubscription.java

@@ -0,0 +1,82 @@
+package timely.api;
+
+import java.util.Map;
+import java.util.Optional;
+
+public class AddSubscription extends SubscriptionRequest {
+
+    private String operation = "add";
+    private String metric = null;
+    private Optional<Map<String, String>> tags = Optional.empty();
+    private Optional<Long> startTime = Optional.empty();
+    private Optional<Long> endTime = Optional.empty();
+    private Optional<Long> delayTime = Optional.empty();
+
+    public String getOperation() {
+        return operation;
+    }
+
+    public String getMetric() {
+        return metric;
+    }
+
+    public Optional<Map<String, String>> getTags() {
+        return tags;
+    }
+
+    public Optional<Long> getStartTime() {
+        return startTime;
+    }
+
+    public Optional<Long> getDelayTime() {
+        return delayTime;
+    }
+
+    public void setMetric(String metric) {
+        this.metric = metric;
+    }
+
+    public void setTags(Optional<Map<String, String>> tags) {
+        this.tags = tags;
+    }
+
+    public void setStartTime(Optional<Long> startTime) {
+        this.startTime = startTime;
+    }
+
+    public void setDelayTime(Optional<Long> delayTime) {
+        this.delayTime = delayTime;
+    }
+
+    public Optional<Long> getEndTime() {
+        return endTime;
+    }
+
+    public void setEndTime(Optional<Long> endTime) {
+        this.endTime = endTime;
+    }
+
+    @Override
+    public int hashCode() {
+        return (operation + subscriptionId + metric + tags + startTime + endTime + delayTime).hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (null == obj) {
+            return false;
+        }
+        if (obj == this) {
+            return true;
+        }
+        if (obj instanceof AddSubscription) {
+            AddSubscription other = (AddSubscription) obj;
+            return (this.subscriptionId.equals(other.subscriptionId) && this.metric.equals(other.metric)
+                    && this.tags.equals(other.tags) && this.startTime.equals(other.startTime)
+                    && this.endTime.equals(other.endTime) && this.delayTime.equals(other.delayTime));
+        } else {
+            return false;
+        }
+    }
+
+}

client/src/main/java/timely/api/BasicAuthLogin.java

@@ -0,0 +1,45 @@
+package timely.api;
+
+public class BasicAuthLogin {
+
+    protected String username;
+    protected String password;
+
+    public String getUsername() {
+        return username;
+    }
+
+    public void setUsername(String user) {
+        this.username = user;
+    }
+
+    public String getPassword() {
+        return password;
+    }
+
+    public void setPassword(String password) {
+        this.password = password;
+    }
+
+    @Override
+    public int hashCode() {
+        return (username + password).hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (null == obj) {
+            return false;
+        }
+        if (obj == this) {
+            return true;
+        }
+        if (obj instanceof BasicAuthLogin) {
+            BasicAuthLogin other = (BasicAuthLogin) obj;
+            return (this.username.equals(other.username) && this.password.equals(other.password));
+        } else {
+            return false;
+        }
+    }
+
+}

client/src/main/java/timely/api/CloseSubscription.java

@@ -0,0 +1,32 @@
+package timely.api;
+
+public class CloseSubscription extends SubscriptionRequest {
+
+    private String operation = "close";
+
+    public String getOperation() {
+        return operation;
+    }
+
+    @Override
+    public int hashCode() {
+        return (operation + subscriptionId).hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (null == obj) {
+            return false;
+        }
+        if (obj == this) {
+            return true;
+        }
+        if (obj instanceof CloseSubscription) {
+            CloseSubscription other = (CloseSubscription) obj;
+            return (this.subscriptionId.equals(other.subscriptionId));
+        } else {
+            return false;
+        }
+    }
+
+}

client/src/main/java/timely/api/CreateSubscription.java

@@ -0,0 +1,32 @@
+package timely.api;
+
+public class CreateSubscription extends SubscriptionRequest {
+
+    private String operation = "create";
+
+    public String getOperation() {
+        return operation;
+    }
+
+    @Override
+    public int hashCode() {
+        return (operation + subscriptionId).hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (null == obj) {
+            return false;
+        }
+        if (obj == this) {
+            return true;
+        }
+        if (obj instanceof CreateSubscription) {
+            CreateSubscription other = (CreateSubscription) obj;
+            return (this.subscriptionId.equals(other.subscriptionId));
+        } else {
+            return false;
+        }
+    }
+
+}

client/src/main/java/timely/api/RemoveSubscription.java

@@ -0,0 +1,41 @@
+package timely.api;
+
+public class RemoveSubscription extends SubscriptionRequest {
+
+    private String operation = "remove";
+    private String metric = null;
+
+    public String getOperation() {
+        return operation;
+    }
+
+    public String getMetric() {
+        return metric;
+    }
+
+    public void setMetric(String metric) {
+        this.metric = metric;
+    }
+
+    @Override
+    public int hashCode() {
+        return (operation + subscriptionId + metric).hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (null == obj) {
+            return false;
+        }
+        if (obj == this) {
+            return true;
+        }
+        if (obj instanceof RemoveSubscription) {
+            RemoveSubscription other = (RemoveSubscription) obj;
+            return (this.subscriptionId.equals(other.subscriptionId) && this.metric.equals(other.metric));
+        } else {
+            return false;
+        }
+    }
+
+}

client/src/main/java/timely/api/SubscriptionRequest.java

@@ -0,0 +1,15 @@
+package timely.api;
+
+public abstract class SubscriptionRequest {
+
+    protected String subscriptionId = null;
+
+    public final String getSubscriptionId() {
+        return subscriptionId;
+    }
+
+    public final void setSubscriptionId(String subscriptionId) {
+        this.subscriptionId = subscriptionId;
+    }
+
+}

client/src/main/java/timely/api/response/MetricResponse.java

@@ -0,0 +1,125 @@
+package timely.api.response;
+
+import java.util.List;
+
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import org.apache.commons.lang3.builder.HashCodeBuilder;
+import org.apache.commons.lang3.builder.ToStringBuilder;
+import timely.model.Metric;
+import timely.model.Tag;
+
+public class MetricResponse {
+
+    private String metric;
+    private long timestamp;
+    private double value;
+    private List<Tag> tags;
+    private String subscriptionId;
+    private boolean complete = false;
+
+    public String getMetric() {
+        return metric;
+    }
+
+    public long getTimestamp() {
+        return timestamp;
+    }
+
+    public double getValue() {
+        return value;
+    }
+
+    public List<Tag> getTags() {
+        return tags;
+    }
+
+    public boolean isComplete() {
+        return complete;
+    }
+
+    public void setMetric(String metric) {
+        this.metric = metric;
+    }
+
+    public void setTimestamp(long timestamp) {
+        this.timestamp = timestamp;
+    }
+
+    public void setValue(double value) {
+        this.value = value;
+    }
+
+    public void setTags(List<Tag> tags) {
+        this.tags = tags;
+    }
+
+    public String getSubscriptionId() {
+        return subscriptionId;
+    }
+
+    public void setSubscriptionId(String subscriptionId) {
+        this.subscriptionId = subscriptionId;
+    }
+
+    public void setComplete(boolean closed) {
+        this.complete = closed;
+    }
+
+    public static MetricResponse fromMetric(Metric metric, String subscriptionId) {
+        MetricResponse response = new MetricResponse();
+        response.setMetric(metric.getName());
+        response.setTimestamp(metric.getValue().getTimestamp());
+        response.setTags(metric.getTags());
+        response.setValue(metric.getValue().getMeasure());
+        response.setSubscriptionId(subscriptionId);
+        response.setComplete(false);
+        return response;
+    }
+
+    @Override
+    public int hashCode() {
+        HashCodeBuilder hash = new HashCodeBuilder();
+        hash.append(this.metric);
+        hash.append(this.timestamp);
+        hash.append(this.value);
+        hash.append(this.tags);
+        hash.append(this.subscriptionId);
+        hash.append(this.complete);
+        return hash.hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (null == obj) {
+            return false;
+        }
+        if (this == obj) {
+            return true;
+        }
+        if (!(obj instanceof MetricResponse)) {
+            return false;
+        }
+        MetricResponse other = (MetricResponse) obj;
+        EqualsBuilder equals = new EqualsBuilder();
+        equals.append(this.metric, other.metric);
+        equals.append(this.timestamp, other.timestamp);
+        equals.append(this.value, other.value);
+        equals.append(this.tags, other.tags);
+        equals.append(this.subscriptionId, other.subscriptionId);
+        equals.append(this.complete, other.complete);
+        return equals.isEquals();
+    }
+
+    @Override
+    public String toString() {
+        ToStringBuilder tsb = new ToStringBuilder(this);
+        tsb.append("metric", this.metric);
+        tsb.append("timestamp", this.timestamp);
+        tsb.append("value", this.value);
+        tsb.append("tags", this.tags);
+        tsb.append("subscriptionId", this.subscriptionId);
+        tsb.append("complete", this.complete);
+        return tsb.toString();
+    }
+
+}

client/src/main/java/timely/api/response/MetricResponses.java

@@ -0,0 +1,29 @@
+package timely.api.response;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class MetricResponses {
+
+    private List<MetricResponse> responses = new ArrayList<>();
+
+    public synchronized List<MetricResponse> getResponses() {
+        return this.responses;
+    }
+
+    public synchronized void setResponses(List<MetricResponse> responses) {
+        this.responses = responses;
+    }
+
+    public synchronized void addResponse(MetricResponse r) {
+        this.responses.add(r);
+    }
+
+    public int size() {
+        return this.responses.size();
+    }
+
+    public synchronized void clear() {
+        this.responses.clear();
+    }
+}

client/src/main/java/timely/client/http/HttpClient.java

@@ -0,0 +1,73 @@
+package timely.client.http;
+
+import javax.net.ssl.HostnameVerifier;
+import javax.net.ssl.SSLContext;
+
+import org.apache.http.client.CookieStore;
+import org.apache.http.client.config.CookieSpecs;
+import org.apache.http.client.config.RequestConfig;
+import org.apache.http.conn.ssl.NoopHostnameVerifier;
+import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.apache.http.impl.client.HttpClientBuilder;
+import org.apache.http.impl.client.HttpClients;
+import org.glassfish.tyrus.client.SslContextConfigurator;
+
+public class HttpClient {
+
+    public static SSLContext getSSLContext(String trustStoreFile, String trustStoreType, String trustStorePass,
+            String keyStoreFile, String keyStoreType, String keyStorePass) {
+        SslContextConfigurator scc = new SslContextConfigurator();
+        scc.setTrustStoreFile(trustStoreFile);
+        scc.setTrustStoreType(trustStoreType);
+        if (null != trustStorePass) {
+            scc.setTrustStorePassword(trustStorePass);
+        }
+        scc.setKeyStoreFile(keyStoreFile);
+        scc.setKeyStoreType(keyStoreType);
+        if (null != keyStorePass) {
+            scc.setKeyStorePassword(keyStorePass);
+        }
+        return scc.createSSLContext();
+    }
+
+    public static CloseableHttpClient get(String trustStoreFile, String trustStoreType, String trustStorePass,
+            String keyStoreFile, String keyStoreType, String keyStorePass, CookieStore cookieStore,
+            boolean hostVerificationEnabled) {
+
+        SSLContext ssl = getSSLContext(trustStoreFile, trustStoreType, trustStorePass, keyStoreFile, keyStoreType,
+                keyStorePass);
+        return get(ssl, cookieStore, hostVerificationEnabled);
+    }
+
+    public static CloseableHttpClient get(SSLContext ssl, CookieStore cookieStore, boolean hostVerificationEnabled) {
+        return get(ssl, cookieStore, hostVerificationEnabled, false);
+    }
+
+    public static CloseableHttpClient get(SSLContext ssl, CookieStore cookieStore, boolean hostVerificationEnabled,
+            boolean clientAuth) {
+        HostnameVerifier hostnameVerifier;
+        if (hostVerificationEnabled) {
+            hostnameVerifier = SSLConnectionSocketFactory.getDefaultHostnameVerifier();
+        } else {
+            hostnameVerifier = new NoopHostnameVerifier();
+        }
+        RequestConfig defaultRequestConfig = RequestConfig.custom().setCookieSpec(CookieSpecs.STANDARD).build();
+        HttpClientBuilder builder;
+        if (cookieStore == null) {
+            builder = HttpClients.custom().setSSLContext(ssl).disableCookieManagement()
+                    .setDefaultRequestConfig(defaultRequestConfig).setSSLHostnameVerifier(hostnameVerifier);
+        } else {
+            builder = HttpClients.custom().setSSLContext(ssl).setDefaultCookieStore(cookieStore)
+                    .setDefaultRequestConfig(defaultRequestConfig).setSSLHostnameVerifier(hostnameVerifier);
+        }
+
+        if (clientAuth) {
+            SSLConnectionSocketFactory sslCSF = new SSLConnectionSocketFactory(ssl,
+                    new String[] { "TLSv1.1", "TLSv1.2" }, null, hostnameVerifier);
+            builder.setSSLSocketFactory(sslCSF);
+        }
+        return builder.build();
+    }
+
+}

client/src/main/java/timely/client/tcp/TcpClient.java

@@ -0,0 +1,124 @@
+package timely.client.tcp;
+
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.io.OutputStreamWriter;
+import java.net.Socket;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class TcpClient implements AutoCloseable {
+
+    private static final Logger LOG = LoggerFactory.getLogger(TcpClient.class);
+
+    private final String host;
+    private final int port;
+    private Socket sock = null;
+    private BufferedWriter out = null;
+    private long connectTime = 0L;
+    private long backoff = 2000;
+    private int bufferSize = -1;
+    private int writesSinceFlush = 0;
+
+    public TcpClient(String hostname, int port) {
+        this(hostname, port, -1);
+    }
+
+    public TcpClient(String hostname, int port, int bufferSize) {
+        this.host = hostname;
+        this.port = port;
+        this.bufferSize = bufferSize;
+    }
+
+    /**
+     * Opens a TCP connection to the specified host and port
+     * 
+     * @throws IOException
+     *             if an error occurs
+     */
+    public void open() throws IOException {
+        if (connect() != 0) {
+            throw new IOException();
+        }
+    }
+
+    /**
+     * Write a metric to Timely
+     * 
+     * @param metric
+     *            newline terminated string representation of Timely metric
+     */
+    public synchronized void write(String metric) throws IOException {
+        if (connect() != 0) {
+            throw new IOException();
+        }
+        out.write(metric);
+        writesSinceFlush++;
+        if (bufferSize > 0 && writesSinceFlush >= bufferSize) {
+            flush();
+        }
+    }
+
+    public synchronized void flush() throws IOException {
+        if (null != out) {
+            out.flush();
+            writesSinceFlush = 0;
+        }
+    }
+
+    /**
+     * Closes the tcp connection to Timely
+     * 
+     * @throws IOException
+     *             if an error occurs
+     */
+    @Override
+    public void close() throws IOException {
+        LOG.trace("Shutting down connection to Timely at {}:{}", host, port);
+        if (null != sock) {
+            try {
+                if (null != out) {
+                    if (bufferSize > 0) {
+                        flush();
+                    }
+                    out.close();
+                }
+                sock.close();
+            } catch (IOException e) {
+                LOG.error("Error closing connection to Timely at " + host + ":" + port + ". Error: " + e.getMessage());
+            } finally {
+                sock = null;
+            }
+        }
+    }
+
+    private synchronized int connect() {
+        if (null == sock || !sock.isConnected()) {
+            if (System.currentTimeMillis() > (connectTime + backoff)) {
+                try {
+                    connectTime = System.currentTimeMillis();
+                    sock = new Socket(host, port);
+                    out = new BufferedWriter(new OutputStreamWriter(sock.getOutputStream()));
+                    backoff = 2000;
+                    LOG.trace("Connected to Timely at {}:{}", host, port);
+                } catch (IOException e) {
+                    LOG.error("Error connecting to Timely at {}:" + host + ":" + port + ". Error: " + e.getMessage());
+                    backoff = backoff * 2;
+                    sock = null;
+                    out = null;
+                    LOG.info("Will retry connection in {} ms.", backoff);
+                    return -1;
+                }
+            } else {
+                LOG.warn("Not writing to Timely, waiting to reconnect");
+                return -1;
+            }
+        }
+        return 0;
+    }
+
+    public long getConnectTime() {
+        return connectTime;
+    }
+}

client/src/main/java/timely/client/udp/UdpClient.java

@@ -0,0 +1,55 @@
+package timely.client.udp;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import java.io.IOException;
+import java.net.DatagramPacket;
+import java.net.DatagramSocket;
+import java.net.InetSocketAddress;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class UdpClient implements AutoCloseable {
+
+    private static final Logger LOG = LoggerFactory.getLogger(UdpClient.class);
+
+    private final String host;
+    private final int port;
+    private final InetSocketAddress address;
+    private final DatagramPacket packet;
+    private DatagramSocket sock;
+
+    public UdpClient(String host, int port) {
+        this.address = new InetSocketAddress(host, port);
+        this.packet = new DatagramPacket("".getBytes(UTF_8), 0, 0, address.getAddress(), port);
+        this.host = host;
+        this.port = port;
+    }
+
+    public void open() throws IOException {
+        if (null == sock) {
+            this.sock = new DatagramSocket();
+        }
+    }
+
+    public void write(String metric) throws IOException {
+        if (null == this.sock) {
+            throw new IllegalStateException("Must call open first");
+        }
+        this.packet.setData(metric.getBytes(UTF_8));
+        LOG.info("writing '" + metric + "' to " + this.host + ":" + this.port);
+        this.sock.send(packet);
+    }
+
+    public void flush() throws IOException {
+    }
+
+    public void close() throws IOException {
+        if (null != sock) {
+            sock.close();
+            sock = null;
+        }
+    }
+
+}

client/src/main/java/timely/client/websocket/ClientHandler.java

@@ -0,0 +1,43 @@
+package timely.client.websocket;
+
+import java.util.List;
+import java.util.Map;
+
+import javax.websocket.CloseReason;
+import javax.websocket.Endpoint;
+import javax.websocket.EndpointConfig;
+import javax.websocket.MessageHandler;
+import javax.websocket.Session;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public abstract class ClientHandler extends Endpoint {
+
+    private final static Logger LOG = LoggerFactory.getLogger(ClientHandler.class);
+
+    @Override
+    public void onOpen(Session session, EndpointConfig config) {
+        LOG.info("Websocket session {} opened.", session.getId());
+        session.addMessageHandler(new MessageHandler.Whole<String>() {
+
+            @Override
+            public void onMessage(String message) {
+                LOG.info("Message received on Websocket session {}: {}", session.getId(), message);
+            }
+        });
+    }
+
+    @Override
+    public void onClose(Session session, CloseReason reason) {
+        LOG.info("Websocket session {} closed.", session.getId());
+    }
+
+    @Override
+    public void onError(Session session, Throwable error) {
+        LOG.error("Error occurred on Websocket session" + session.getId(), error);
+    }
+
+    public void beforeRequest(Map<String, List<String>> headers) {
+    }
+}

client/src/main/java/timely/client/websocket/TimelyEndpointConfig.java

@@ -0,0 +1,68 @@
+package timely.client.websocket;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import javax.websocket.ClientEndpointConfig;
+import javax.websocket.Decoder;
+import javax.websocket.Encoder;
+import javax.websocket.Extension;
+
+import org.apache.http.cookie.Cookie;
+
+public class TimelyEndpointConfig implements ClientEndpointConfig {
+
+    private String sessionCookie = null;
+    private final ClientHandler clientEndpoint;
+
+    private static final String FORMAT = "%s=%s;";
+
+    public TimelyEndpointConfig(ClientHandler clientEndpoint, Cookie sessionCookie) {
+        if (null != sessionCookie) {
+            this.sessionCookie = String.format(FORMAT, sessionCookie.getName(), sessionCookie.getValue());
+        }
+        this.clientEndpoint = clientEndpoint;
+    }
+
+    @Override
+    public List<Class<? extends Encoder>> getEncoders() {
+        return Collections.emptyList();
+    }
+
+    @Override
+    public List<Class<? extends Decoder>> getDecoders() {
+        return Collections.emptyList();
+    }
+
+    @Override
+    public Map<String, Object> getUserProperties() {
+        return Collections.emptyMap();
+    }
+
+    @Override
+    public List<String> getPreferredSubprotocols() {
+        return Collections.emptyList();
+    }
+
+    @Override
+    public List<Extension> getExtensions() {
+        return Collections.emptyList();
+    }
+
+    @Override
+    public Configurator getConfigurator() {
+        return new Configurator() {
+
+            @Override
+            public void beforeRequest(Map<String, List<String>> headers) {
+                super.beforeRequest(headers);
+                if (null != sessionCookie) {
+                    headers.put("Cookie", Collections.singletonList(sessionCookie));
+                }
+                TimelyEndpointConfig.this.clientEndpoint.beforeRequest(headers);
+            }
+        };
+    }
+
+}

client/src/main/java/timely/client/websocket/WebSocketClient.java

@@ -0,0 +1,178 @@
+package timely.client.websocket;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.nio.ByteBuffer;
+import java.util.concurrent.TimeUnit;
+
+import javax.net.ssl.SSLContext;
+import javax.websocket.DeploymentException;
+import javax.websocket.Session;
+
+import com.google.common.base.Preconditions;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.http.HttpResponse;
+import org.apache.http.HttpStatus;
+import org.apache.http.client.HttpResponseException;
+import org.apache.http.client.methods.HttpGet;
+import org.apache.http.client.methods.HttpPost;
+import org.apache.http.client.methods.HttpRequestBase;
+import org.apache.http.client.utils.HttpClientUtils;
+import org.apache.http.cookie.Cookie;
+import org.apache.http.entity.StringEntity;
+import org.apache.http.impl.client.BasicCookieStore;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.glassfish.tyrus.client.ClientManager;
+import org.glassfish.tyrus.client.ClientProperties;
+import org.glassfish.tyrus.client.SslEngineConfigurator;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.api.BasicAuthLogin;
+import timely.client.http.HttpClient;
+import timely.serialize.JsonSerializer;
+
+public class WebSocketClient implements AutoCloseable {
+
+    private static final Logger LOG = LoggerFactory.getLogger(WebSocketClient.class);
+
+    private final String timelyHostname;
+    private final int timelyHttpsPort;
+    private final int timelyWssPort;
+    private final boolean doLogin;
+    private final boolean clientAuth;
+    private final String timelyUsername;
+    private final String timelyPassword;
+    private final boolean hostVerificationEnabled;
+    private final int bufferSize;
+    private final SSLContext ssl;
+
+    private ClientManager webSocketClient = null;
+    protected Session session = null;
+    protected volatile boolean closed = true;
+
+    protected WebSocketClient(SSLContext ssl, String timelyHostname, int timelyHttpsPort, int timelyWssPort,
+            boolean clientAuth, boolean doLogin, String timelyUsername, String timelyPassword,
+            boolean hostVerificationEnabled, int bufferSize) {
+        this.ssl = ssl;
+        this.timelyHostname = timelyHostname;
+        this.timelyHttpsPort = timelyHttpsPort;
+        this.timelyWssPort = timelyWssPort;
+        this.doLogin = doLogin;
+        this.clientAuth = clientAuth;
+        this.timelyUsername = timelyUsername;
+        this.timelyPassword = timelyPassword;
+        this.hostVerificationEnabled = hostVerificationEnabled;
+        this.bufferSize = bufferSize;
+
+        Preconditions.checkNotNull(timelyHostname, "%s must be supplied", "Timely host name");
+        Preconditions.checkNotNull(timelyHttpsPort, "%s must be supplied", "Timely HTTPS port");
+        Preconditions.checkNotNull(timelyWssPort, "%s must be supplied", "Timely WSS port");
+
+        if (doLogin && !clientAuth) {
+            if ((StringUtils.isEmpty(timelyUsername) && !StringUtils.isEmpty(timelyPassword)
+                    || (!StringUtils.isEmpty(timelyUsername) && StringUtils.isEmpty(timelyPassword)))) {
+                throw new IllegalArgumentException("Both Timely username and password must be empty or non-empty");
+            }
+        }
+    }
+
+    protected WebSocketClient(String timelyHostname, int timelyHttpsPort, int timelyWssPort, boolean clientAuth,
+            boolean doLogin, String timelyUsername, String timelyPassword, String keyStoreFile, String keyStoreType,
+            String keyStorePass, String trustStoreFile, String trustStoreType, String trustStorePass,
+            boolean hostVerificationEnabled, int bufferSize) {
+        this(HttpClient.getSSLContext(trustStoreFile, trustStoreType, trustStorePass, keyStoreFile, keyStoreType,
+                keyStorePass), timelyHostname, timelyHttpsPort, timelyWssPort, clientAuth, doLogin, timelyUsername,
+                timelyPassword, hostVerificationEnabled, bufferSize);
+    }
+
+    public void open(ClientHandler clientEndpoint) throws IOException, DeploymentException, URISyntaxException {
+        Cookie sessionCookie = null;
+        if (doLogin) {
+            BasicCookieStore cookieJar = new BasicCookieStore();
+            try (CloseableHttpClient client = HttpClient.get(ssl, cookieJar, hostVerificationEnabled, clientAuth)) {
+
+                String target = "https://" + timelyHostname + ":" + timelyHttpsPort + "/login";
+
+                HttpRequestBase request = null;
+                if (StringUtils.isEmpty(timelyUsername)) {
+                    // HTTP GET to /login to use certificate based login
+                    request = new HttpGet(target);
+                    LOG.trace("Performing client certificate login");
+                } else {
+                    // HTTP POST to /login to use username/password
+                    BasicAuthLogin login = new BasicAuthLogin();
+                    login.setUsername(timelyUsername);
+                    login.setPassword(timelyPassword);
+                    String payload = JsonSerializer.getObjectMapper().writeValueAsString(login);
+                    HttpPost post = new HttpPost(target);
+                    post.setEntity(new StringEntity(payload));
+                    request = post;
+                    LOG.trace("Performing BasicAuth login");
+                }
+
+                HttpResponse response = null;
+                try {
+                    response = client.execute(request);
+                    if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
+                        throw new HttpResponseException(response.getStatusLine().getStatusCode(),
+                                response.getStatusLine().getReasonPhrase());
+                    }
+                    for (Cookie c : cookieJar.getCookies()) {
+                        if (c.getName().equals("TSESSIONID")) {
+                            sessionCookie = c;
+                            break;
+                        }
+                    }
+                    if (null == sessionCookie) {
+                        throw new IllegalStateException(
+                                "Unable to find TSESSIONID cookie header in Timely login response");
+                    }
+                } finally {
+                    HttpClientUtils.closeQuietly(response);
+                }
+            }
+        }
+
+        SslEngineConfigurator sslEngine = new SslEngineConfigurator(ssl);
+        sslEngine.setClientMode(true);
+        sslEngine.setHostVerificationEnabled(hostVerificationEnabled);
+
+        webSocketClient = ClientManager.createClient();
+        webSocketClient.getProperties().put(ClientProperties.SSL_ENGINE_CONFIGURATOR, sslEngine);
+        webSocketClient.getProperties().put(ClientProperties.INCOMING_BUFFER_SIZE, bufferSize);
+        String wssPath = "wss://" + timelyHostname + ":" + timelyWssPort + "/websocket";
+        session = webSocketClient.connectToServer(clientEndpoint,
+                new TimelyEndpointConfig(clientEndpoint, sessionCookie), new URI(wssPath));
+
+        final ByteBuffer pingData = ByteBuffer.allocate(0);
+        webSocketClient.getScheduledExecutorService().scheduleAtFixedRate(() -> {
+            try {
+                session.getBasicRemote().sendPing(pingData);
+            } catch (Exception e) {
+                LOG.error("Error sending ping", e);
+            }
+        }, 30, 60, TimeUnit.SECONDS);
+        closed = false;
+    }
+
+    public synchronized void close() throws IOException {
+        if (closed) {
+            return;
+        }
+        try {
+            if (null != webSocketClient) {
+                webSocketClient.shutdown();
+            }
+        } finally {
+            session = null;
+            webSocketClient = null;
+            closed = true;
+        }
+    }
+
+    public boolean isClosed() {
+        return closed;
+    }
+
+}

client/src/main/java/timely/client/websocket/subscription/WebSocketSubscriptionClient.java

@@ -0,0 +1,91 @@
+package timely.client.websocket.subscription;
+
+import java.io.IOException;
+import java.net.URISyntaxException;
+import java.util.Map;
+import java.util.Optional;
+import java.util.UUID;
+import java.util.concurrent.Future;
+
+import javax.net.ssl.SSLContext;
+import javax.websocket.CloseReason;
+import javax.websocket.DeploymentException;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import timely.api.AddSubscription;
+import timely.api.CloseSubscription;
+import timely.api.CreateSubscription;
+import timely.api.RemoveSubscription;
+import timely.client.websocket.ClientHandler;
+import timely.client.websocket.WebSocketClient;
+import timely.serialize.JsonSerializer;
+
+public class WebSocketSubscriptionClient extends WebSocketClient {
+
+    private static final Logger LOG = LoggerFactory.getLogger(WebSocketSubscriptionClient.class);
+    private final String subscriptionId;
+
+    public WebSocketSubscriptionClient(SSLContext ssl, String timelyHostname, int timelyHttpsPort, int timelyWssPort,
+            boolean clientAuth, boolean doLogin, String timelyUsername, String timelyPassword,
+            boolean hostVerificationEnabled, int bufferSize) {
+        super(ssl, timelyHostname, timelyHttpsPort, timelyWssPort, clientAuth, doLogin, timelyUsername, timelyPassword,
+                hostVerificationEnabled, bufferSize);
+        subscriptionId = UUID.randomUUID().toString();
+        LOG.trace("Created WebSocketClient with subscriptionId {}", this.subscriptionId);
+    }
+
+    public WebSocketSubscriptionClient(String timelyHostname, int timelyHttpsPort, int timelyWssPort,
+            boolean clientAuth, boolean doLogin, String timelyUsername, String timelyPassword, String keyStoreFile,
+            String keyStoreType, String keyStorePass, String trustStoreFile, String trustStoreType,
+            String trustStorePass, boolean hostVerificationEnabled, int bufferSize) {
+        super(timelyHostname, timelyHttpsPort, timelyWssPort, clientAuth, doLogin, timelyUsername, timelyPassword,
+                keyStoreFile, keyStoreType, keyStorePass, trustStoreFile, trustStoreType, trustStorePass,
+                hostVerificationEnabled, bufferSize);
+        subscriptionId = UUID.randomUUID().toString();
+        LOG.trace("Created WebSocketClient with subscriptionId {}", this.subscriptionId);
+    }
+
+    @Override
+    public void open(ClientHandler clientEndpoint) throws IOException, DeploymentException, URISyntaxException {
+        super.open(clientEndpoint);
+        CreateSubscription create = new CreateSubscription();
+        create.setSubscriptionId(subscriptionId);
+        session.getBasicRemote().sendText(JsonSerializer.getObjectMapper().writeValueAsString(create));
+    }
+
+    @Override
+    public synchronized void close() throws IOException {
+        if (null != session) {
+            CloseSubscription close = new CloseSubscription();
+            close.setSubscriptionId(subscriptionId);
+            try {
+                session.getBasicRemote().sendText(JsonSerializer.getObjectMapper().writeValueAsString(close));
+                session.close(new CloseReason(CloseReason.CloseCodes.NORMAL_CLOSURE, "Client called close."));
+            } catch (Exception e) {
+                LOG.info("Unable to send close message to server: {}", e.getMessage());
+            }
+        }
+        super.close();
+    }
+
+    public Future<Void> addSubscription(String metric, Map<String, String> tags, long startTime, long endTime,
+            long delayTime) throws IOException {
+        AddSubscription add = new AddSubscription();
+        add.setSubscriptionId(subscriptionId);
+        add.setMetric(metric);
+        add.setTags(Optional.ofNullable(tags));
+        add.setStartTime(Optional.ofNullable(startTime));
+        add.setEndTime(Optional.ofNullable(endTime));
+        add.setDelayTime(Optional.ofNullable(delayTime));
+        return session.getAsyncRemote().sendText(JsonSerializer.getObjectMapper().writeValueAsString(add));
+    }
+
+    public Future<Void> removeSubscription(String metric) throws Exception {
+        RemoveSubscription remove = new RemoveSubscription();
+        remove.setSubscriptionId(subscriptionId);
+        remove.setMetric(metric);
+        return session.getAsyncRemote().sendText(JsonSerializer.getObjectMapper().writeValueAsString(remove));
+    }
+
+}

client/src/main/java/timely/model/Metric.java

@@ -0,0 +1,189 @@
+package timely.model;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import com.fasterxml.jackson.annotation.JsonGetter;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import com.fasterxml.jackson.annotation.JsonRootName;
+import com.fasterxml.jackson.annotation.JsonUnwrapped;
+import timely.model.parse.TagParser;
+
+/**
+ * A Metric consists of a metric name, tags, and a Value
+ *
+ * Json has been flattened to reduce overhead. Example:
+ * {"name":"m1","timestamp":1,"measure":1.0,"tags":[{"k1":"v1"}]}
+ *
+ */
+@JsonRootName("metric")
+@JsonInclude(JsonInclude.Include.NON_NULL)
+@JsonPropertyOrder({ "name" })
+public class Metric implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    private String name;
+    private List<Tag> tags;
+    private Value value;
+
+    public Metric() {
+        tags = new ArrayList<>();
+        value = new Value();
+    }
+
+    public Metric(Metric other) {
+        this();
+        this.name = other.getName();
+        this.tags.addAll(other.getTags());
+        this.value = new Value(other.getValue());
+    }
+
+    public Metric(String name, long timestamp, double measure) {
+        this();
+        this.name = name;
+        this.value.setTimestamp(timestamp);
+        this.value.setMeasure(measure);
+    }
+
+    public Metric(String name, long timestamp, double measure, List<Tag> tags) {
+        this(name, timestamp, measure);
+        this.setTags(tags);
+    }
+
+    public Metric(String name, List<Tag> tags) {
+        this();
+        this.name = name;
+        this.setTags(tags);
+    }
+
+    public static Builder newBuilder() {
+        return new Builder();
+    }
+
+    @JsonGetter("name")
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    @JsonGetter("tags")
+    public List<Tag> getTags() {
+        return tags;
+    }
+
+    public void setTags(List<Tag> tags) {
+        this.tags.addAll(tags);
+    }
+
+    public void addTag(Tag tag) {
+        tags.add(new Tag(tag));
+    }
+
+    @JsonUnwrapped
+    public Value getValue() {
+        return value;
+    }
+
+    public void setValue(Value value) {
+        this.value = value;
+    }
+
+    @Override
+    public String toString() {
+        Collections.sort(tags);
+        return "Metric{" + "name='" + name + '\'' + ", tags=" + tags + ", value=" + value + '}';
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o)
+            return true;
+        if (o == null || getClass() != o.getClass())
+            return false;
+
+        Metric metric = (Metric) o;
+
+        if (name != null ? !name.equals(metric.name) : metric.name != null)
+            return false;
+
+        if (tags != null) {
+            if (tags.size() != metric.tags.size()) {
+                return false;
+            } else if (!tags.containsAll(metric.tags)) {
+                return false;
+            }
+        }
+
+        return value != null ? value.equals(metric.value) : metric.value == null;
+
+    }
+
+    @Override
+    public int hashCode() {
+        int result = name != null ? name.hashCode() : 0;
+        result = 31 * result + (tags != null ? tags.hashCode() : 0);
+        result = 31 * result + (value != null ? value.hashCode() : 0);
+        return result;
+    }
+
+    /**
+     * Simple Builder for Metric. Note: cannot re-use a builder after build is
+     * called.
+     */
+    public static class Builder {
+
+        Metric metric;
+
+        private Builder() {
+            metric = new Metric();
+        }
+
+        private static TagParser parser = new TagParser();
+
+        public Builder tag(Tag tag) {
+            metric.addTag(tag);
+            return this;
+        }
+
+        public Builder tags(List<Tag> tags) {
+            metric.setTags(tags);
+            return this;
+        }
+
+        public Builder tag(String key, String value) {
+            metric.addTag(new Tag(key, value));
+            return this;
+        }
+
+        public Builder tag(String rawTag) {
+            metric.addTag(parser.parse(rawTag));
+            return this;
+        }
+
+        public Builder name(String name) {
+            metric.setName(name);
+            return this;
+        }
+
+        public Builder value(Value value) {
+            metric.setValue(value);
+            return this;
+        }
+
+        public Builder value(long timestamp, double measure) {
+            metric.setValue(new Value(timestamp, measure));
+            return this;
+        }
+
+        public Metric build() {
+            return this.metric;
+        }
+    }
+}

client/src/main/java/timely/model/ObjectSizeOf.java

@@ -0,0 +1,196 @@
+package timely.model;
+
+import java.lang.reflect.Array;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.Stack;
+import java.util.logging.Logger;
+
+/**
+ * A simple interface that objects can implement to return the object size.
+ */
+public interface ObjectSizeOf {
+
+    /**
+     * The (approximate) size of the object
+     */
+    long sizeInBytes();
+
+    public static class ObjectInstance {
+
+        private Object o;
+
+        public ObjectInstance(Object _o) {
+            this.o = _o;
+        }
+
+        public Object getObject() {
+            return o;
+        }
+
+        @Override
+        public int hashCode() {
+            return System.identityHashCode(o);
+        }
+
+        @Override
+        public boolean equals(Object obj) {
+            if (!(obj instanceof ObjectInstance)) {
+                return false;
+            }
+            return ((ObjectInstance) obj).o == this.o;
+        }
+    }
+
+    public static class Sizer {
+
+        private static final Logger log = Logger.getLogger(Sizer.class.getCanonicalName());
+        public static final short OBJECT_OVERHEAD = 8;
+        public static final short ARRAY_OVERHEAD = 12;
+        public static final short REFERENCE = 4;
+        // The size of the basic Number constructs (and Boolean and Character)
+        // is 16: roundUp(8 + primitiveSize)
+        public static final short NUMBER_SIZE = 16;
+
+        /**
+         * Get the size of an object. Note that we want something relatively fast that
+         * gives us an order of magnitude here. The java Instrumentation agent mechanism
+         * is a little too costly for general use here. This will look for the
+         * ObjectSizeOf interface and if implemented on the object will use that.
+         * Otherwise it will do a simple navigation of the fields using reflection.
+         *
+         * @return an approximation of the object size
+         */
+        public static long getObjectSize(Object o, boolean useSizeInBytesMethod, boolean debug) {
+            long estSize = getObjectSize(o, new HashSet<ObjectInstance>(), new Stack<ObjectInstance>(),
+                    useSizeInBytesMethod, debug);
+            return estSize;
+        }
+
+        public static long getObjectSize(Object o) {
+            long estSize = getObjectSize(o, new HashSet<ObjectInstance>(), new Stack<ObjectInstance>(), true, false);
+            return estSize;
+        }
+
+        public static long getObjectSize(Object o, Set<ObjectInstance> visited, Stack<ObjectInstance> stack,
+                boolean useSizeInBytesMethod, boolean debug) {
+            long totalSize = 0;
+            stack.add(new ObjectInstance(o));
+            while (!stack.isEmpty()) {
+                long size = 0;
+                ObjectInstance oi = stack.pop();
+                o = oi.getObject();
+                if (o != null && !visited.contains(oi)) {
+                    visited.add(oi);
+                    try {
+                        if (useSizeInBytesMethod) {
+                            try {
+                                if (o instanceof ObjectSizeOf) {
+                                    size = ((ObjectSizeOf) o).sizeInBytes();
+                                } else {
+                                    Method sizeInBytes = o.getClass().getMethod("sizeInBytes", (Class<?>[]) null);
+                                    size = (Long) sizeInBytes.invoke(o);
+                                }
+                            } catch (Throwable t) {
+                                // ok, lets do this the hard way...
+                            }
+                        }
+                        if (size == 0) {
+                            // the hard way...
+                            // do not include Class related objects or
+                            // reflection objects
+                            if ((o instanceof Class) || (o instanceof ClassLoader) || (o.getClass().getPackage() != null
+                                    && o.getClass().getPackage().getName().startsWith("java.lang.reflect"))) {
+                                size = 0;
+                            } else if (o instanceof Number || o instanceof Boolean || o instanceof Character) {
+                                size = NUMBER_SIZE;
+                            } else {
+                                // lets do a simple sizing
+                                Class<?> c = o.getClass();
+                                if (c.isArray()) {
+                                    size = ARRAY_OVERHEAD;
+                                    int length = Array.getLength(o);
+                                    if (c.getComponentType().isPrimitive()) {
+                                        size += length * getPrimitiveObjectSize(c.getComponentType());
+                                    } else {
+                                        size += length * REFERENCE;
+                                        for (int i = 0; i < length; i++) {
+                                            Object element = Array.get(o, i);
+                                            if (element != null) {
+                                                stack.add(new ObjectInstance(element));
+                                            }
+                                        }
+                                    }
+                                } else {
+                                    size += OBJECT_OVERHEAD;
+                                    while (c != null) {
+                                        for (Field field : c.getDeclaredFields()) {
+                                            if (Modifier.isStatic(field.getModifiers())) {
+                                                continue;
+                                            }
+                                            if (field.getType().isPrimitive()) {
+                                                size += getPrimitiveObjectSize(field.getType());
+                                            } else {
+                                                size += REFERENCE;
+                                                boolean accessible = field.isAccessible();
+                                                field.setAccessible(true);
+                                                try {
+                                                    Object fieldObject = field.get(o);
+                                                    if (fieldObject != null) {
+                                                        stack.push(new ObjectInstance(fieldObject));
+                                                    }
+                                                } catch (Exception e) {
+                                                    // cannot get to field, so
+                                                    // ignore it in this size
+                                                    // calculation
+                                                    e.printStackTrace();
+                                                }
+                                                field.setAccessible(accessible);
+                                            }
+                                        }
+                                        c = c.getSuperclass();
+                                    }
+                                }
+                                size = roundUp(size);
+                            }
+                        }
+                    } catch (Throwable t) {
+                        log.warning("Unable to determine object size for " + o);
+                    }
+                    if (debug) {
+                        System.out.println(o.getClass().getCanonicalName() + "=" + size);
+                    }
+                }
+                totalSize += size;
+            }
+
+            return totalSize;
+        }
+
+        public static long roundUp(long size) {
+            long extra = size % 8;
+            if (extra > 0) {
+                size = size + 8 - extra;
+            }
+            return size;
+        }
+
+        public static short getPrimitiveObjectSize(Class<?> primitiveType) {
+            if (primitiveType.equals(int.class) || primitiveType.equals(float.class)) {
+                return 4;
+            } else if (primitiveType.equals(boolean.class) || primitiveType.equals(byte.class)) {
+                return 1;
+            } else if (primitiveType.equals(char.class) || primitiveType.equals(short.class)) {
+                return 2;
+            } else if (primitiveType.equals(long.class) || primitiveType.equals(double.class)) {
+                return 8;
+            } else { // if (primitiveType.equals(void.class)) {
+                return 0;
+            }
+        }
+    }
+
+}

client/src/main/java/timely/model/Tag.java

@@ -0,0 +1,109 @@
+package timely.model;
+
+import java.io.Serializable;
+import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import com.fasterxml.jackson.annotation.JsonAnyGetter;
+import com.fasterxml.jackson.annotation.JsonAnySetter;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonRootName;
+import com.google.common.base.Preconditions;
+import org.apache.commons.lang3.builder.CompareToBuilder;
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import timely.model.parse.TagParser;
+
+/**
+ * Tag consists of key value pair
+ */
+@JsonRootName("tag")
+public class Tag implements Comparable<Tag>, Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    private static final TagParser tagParser = new TagParser();
+
+    private String key;
+    private String value;
+
+    public Tag() {
+    }
+
+    public Tag(Tag other) {
+        this.setKey(other.getKey());
+        this.setValue(other.getValue());
+    }
+
+    public Tag(String tag) {
+        this(tagParser.parse(tag));
+    }
+
+    public Tag(String key, String value) {
+        Preconditions.checkNotNull(key);
+        Preconditions.checkNotNull(value);
+        this.setKey(key);
+        this.setValue(value);
+    }
+
+    @JsonAnyGetter
+    public Map<String, String> get() {
+        return Stream.of(this).collect(Collectors.toMap(Tag::getKey, Tag::getValue));
+    }
+
+    @JsonAnySetter
+    public void set(String key, String value) {
+        this.key = key;
+        this.value = value;
+    }
+
+    @JsonIgnore
+    public String getKey() {
+        return key;
+    }
+
+    public void setKey(String key) {
+        this.key = key;
+    }
+
+    @JsonIgnore
+    public String getValue() {
+        return value;
+    }
+
+    public void setValue(String value) {
+        this.value = value;
+    }
+
+    /**
+     * Joins key and value into key=value
+     */
+    public String join() {
+        return tagParser.combine(this);
+    }
+
+    @Override
+    public String toString() {
+        return "Tag{" + join() + "}";
+    }
+
+    @Override
+    public int hashCode() {
+        return this.toString().hashCode();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o)
+            return true;
+        if (null == o || getClass() != o.getClass())
+            return false;
+        Tag other = (Tag) o;
+        return new EqualsBuilder().append(this.key, other.key).append(this.value, other.value).isEquals();
+    }
+
+    @Override
+    public int compareTo(Tag other) {
+        return new CompareToBuilder().append(this.key, other.key).append(this.value, other.value).toComparison();
+    }
+}

client/src/main/java/timely/model/Value.java

@@ -0,0 +1,93 @@
+package timely.model;
+
+import java.io.Serializable;
+import java.util.Comparator;
+import java.util.concurrent.TimeUnit;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.google.common.base.Objects;
+
+/**
+ * Value consists of a long timestamp and a double measurement
+ */
+public class Value implements Comparator<Value>, Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    private Long timestamp;
+    private Double measure;
+
+    public Value() {
+    }
+
+    public Value(Value other) {
+        this.setTimestamp(other.getTimestamp());
+        this.setMeasure(other.getMeasure());
+    }
+
+    @JsonCreator
+    public Value(@JsonProperty("timestamp") Long timestamp, @JsonProperty("measure") Double measure) {
+        this.setTimestamp(timestamp);
+        this.setMeasure(measure);
+    }
+
+    @JsonProperty("timestamp")
+    public Long getTimestamp() {
+        return timestamp;
+    }
+
+    public void setTimestamp(final Long timestamp) {
+        this.setTimestamp(timestamp, TimeUnit.MILLISECONDS);
+    }
+
+    public void setTimestamp(final Long timestamp, TimeUnit timeUnit) {
+        this.timestamp = timeUnit.toMillis(timestamp);
+    }
+
+    @JsonProperty("measure")
+    public Double getMeasure() {
+        return measure;
+    }
+
+    public void setMeasure(final Double measure) {
+        this.measure = measure;
+    }
+
+    @Override
+    /**
+     * Compares timestamps for sorting.
+     *
+     * Note: this comparator imposes orderings that are inconsistent with equals
+     *
+     */
+    public int compare(Value v1, Value v2) {
+        if (v1.getTimestamp().equals(v2.getTimestamp()))
+            return 0;
+        return v1.getTimestamp() > v2.getTimestamp() ? 1 : -1;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o)
+            return true;
+        if (null == o || getClass() != o.getClass())
+            return false;
+
+        if (getTimestamp() != null ? !getTimestamp().equals(((Value) o).getTimestamp())
+                : ((Value) o).getTimestamp() != null)
+            return false;
+        return !(getMeasure() != null ? !getMeasure().equals(((Value) o).getMeasure())
+                : ((Value) o).getMeasure() != null);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hashCode(timestamp, measure);
+    }
+
+    @Override
+    public String toString() {
+        return "Value{" + "timestamp=" + timestamp + ", measure=" + measure + "}";
+    }
+}

client/src/main/java/timely/model/parse/Combiner.java

@@ -0,0 +1,6 @@
+package timely.model.parse;
+
+public interface Combiner<T> {
+
+    String combine(T o);
+}

client/src/main/java/timely/model/parse/MetricParser.java

@@ -0,0 +1,30 @@
+package timely.model.parse;
+
+import java.util.List;
+
+import com.google.common.base.Preconditions;
+import com.google.common.base.Splitter;
+import timely.model.Metric;
+
+public class MetricParser implements Parser<Metric> {
+
+    private static final Splitter spaceSplitter = Splitter.on(" ").omitEmptyStrings().trimResults();
+
+    @Override
+    public Metric parse(String line) {
+
+        // put specification
+        //
+        // put <metricName> <timestamp> <value> <tagK=tagV> <tagK=tagV> ...
+
+        List<String> parts = spaceSplitter.splitToList(line);
+        Preconditions.checkPositionIndex(3, parts.size());
+
+        Metric.Builder builder = Metric.newBuilder();
+        // index 0 is put
+        builder.name(parts.get(1)); // metric name
+        builder.value(Long.parseLong(parts.get(2)), Double.parseDouble(parts.get(3)));
+        parts.stream().skip(4).forEach(builder::tag);
+        return builder.build();
+    }
+}

client/src/main/java/timely/model/parse/Parser.java

@@ -0,0 +1,7 @@
+package timely.model.parse;
+
+@FunctionalInterface
+public interface Parser<T> {
+
+    T parse(String t);
+}

client/src/main/java/timely/model/parse/TagListParser.java

@@ -0,0 +1,60 @@
+package timely.model.parse;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+import timely.model.Tag;
+
+/**
+ * Parses tag1=val1,tag2=val2,tag3=val3 into a {@code List} of {@code Tag}
+ * Combines {@code List} of {@code Tag} into {@code String} of
+ * tag1=val1,tag2=val2,tag3=val3.
+ */
+public class TagListParser implements Parser<List<Tag>>, Combiner<Collection<Tag>> {
+
+    private static final TagParser tagParser = new TagParser();
+
+    @Override
+    public List<Tag> parse(String t) {
+        ArrayList<Tag> tags = new ArrayList<>();
+        // only split on commas that are not preceded with a backslash
+        String[] parts = t.split("(?<!\\\\),");
+        for (String p : parts) {
+            if (!p.isEmpty()) {
+                Tag tag = tagParser.parse(p);
+                // unescape commas in the key and value of the tag
+                tag.setKey(tag.getKey().replaceAll("\\\\,", ","));
+                tag.setValue(tag.getValue().replaceAll("\\\\,", ","));
+                tags.add(tag);
+            }
+        }
+        return tags;
+    }
+
+    @Override
+    public String combine(Collection<Tag> tags) {
+        StringBuilder builder = new StringBuilder();
+        if (!tags.isEmpty()) {
+            tags.forEach(p -> builder.append(tagParser.combine(p)).append(','));
+            builder.setLength(builder.length() - 1);
+        }
+        return builder.toString();
+    }
+
+    /**
+     * An alternative combiner for a map of string to string instead of a list of
+     * tags
+     * 
+     * @return string representation
+     */
+    public String combine(Map<String, String> tags) {
+        StringBuilder builder = new StringBuilder();
+        if (!tags.isEmpty()) {
+            tags.forEach((k, v) -> builder.append(tagParser.combine(new Tag(k, v))).append(','));
+            builder.setLength(builder.length() - 1);
+        }
+        return builder.toString();
+    }
+}

client/src/main/java/timely/model/parse/TagParser.java

@@ -0,0 +1,32 @@
+package timely.model.parse;
+
+import java.util.List;
+
+import com.google.common.base.Joiner;
+import com.google.common.base.Splitter;
+import timely.model.Tag;
+
+/**
+ * Parses tag1=val1 into a {@code Tag} Combines {@code Tag} into {@code String}
+ * of tag1=val1
+ */
+public class TagParser implements Parser<Tag>, Combiner<Tag> {
+
+    private static final Splitter equalSplitter = Splitter.on("=").limit(2).trimResults();
+    private static final Joiner equalsJoiner = Joiner.on("=");
+
+    @Override
+    public Tag parse(String t) {
+        List<String> parts = equalSplitter.splitToList(t);
+        if (parts.size() != 2) {
+            throw new IllegalArgumentException("Invalid tag format: " + t);
+        }
+        return new Tag(parts.get(0), parts.get(1));
+    }
+
+    @Override
+    public String combine(Tag t) {
+        return equalsJoiner.join(t.getKey(), t.getValue());
+    }
+
+}

client/src/main/java/timely/serialize/JsonSerializer.java

@@ -0,0 +1,22 @@
+package timely.serialize;
+
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.datatype.jdk8.Jdk8Module;
+
+public class JsonSerializer {
+
+    private static ObjectMapper mapper = new ObjectMapper();
+
+    static {
+        mapper.registerModule(new Jdk8Module());
+        mapper.configure(DeserializationFeature.ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT, true);
+        mapper.configure(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT, true);
+        mapper.configure(JsonParser.Feature.ALLOW_NON_NUMERIC_NUMBERS, true);
+    }
+
+    public static ObjectMapper getObjectMapper() {
+        return mapper;
+    }
+}

client/src/main/python/template/setup.py

@@ -0,0 +1,12 @@
+from setuptools import setup
+
+setup(
+    name='timely',
+    version='${python.client.version}',
+    packages=['timely'],
+    install_requires=[
+        'seaborn',
+	'plotly'
+    ],
+    license='Apache License, Version 2.0'
+)