Add documentation for Topology Aware Consumption feature

_posts/2012-01-01-design.md

@@ -32,7 +32,7 @@ causing a backlog for other channels (the same applies at the topic level).
 
 A channel can, and generally does, have multiple clients connected. Assuming all connected clients
 are in a state where they are ready to receive messages, each message will be delivered to a random
-client.  For example:
+client (when topology aware consumption is enabled, messages will be delivered at random but with priority based on closest geographical client(s), see [Topology Aware Consumption](#topology-aware-consumption)).  For example:
 
 ![nsqd clients](https://f.cloud.github.com/assets/187441/1700696/f1434dc8-6029-11e3-8a66-18ca4ea10aca.gif)
 
@@ -195,6 +195,16 @@ independent copies of streams (channels), we've produced a daemon that behaves l
 and `pubsub` *combined* . This is powerful in terms of simplifying the topology of our systems where
 we would have traditionally maintained the older toolchain discussed above.
 
+### Topology Aware Consumption
+
+nsqd provides a configuration option `--enable-experiments` that can be used to enable the `topology-aware-consumption` functionality. If this experiment is turned on and configurations are also provided for `--topology-region` and `--topology-zone`, the nsqd will push messages to consumers based on a topology-aware behavior pattern.
+
+Consumers can provide their own topology region and zone via options set in their IDENTIFY message to the nsqd host. If this information is not provided, the consumer will be considered to be outside of both the zone and region of the nsqd.
+
+When configured, nsqd will prioritize the pushing of messages to consumers based on those that are geographically closest to them. It will prioritize first pushing messages to consumers within the same region and zone if possible, then pushing messages to consumers within the same region, and lastly will fall back to pushing to any consumer possible at random (regular behavior).
+
+This behiavor pattern allows for running nsqd in a multiregion application architecture, and to minimize network egress costs for nsqd interacting with consumers in different geolocations.
+
 ### Go
 
 We made a strategic decision early on to build the **NSQ** core in [Go][golang]. We recently blogged

_posts/2012-10-01-nsqadmin.md

@@ -139,15 +139,18 @@ The following metrics are exposed through `nsqadmin` on Topic, Channel and Clien
 * `Messages`: Total count of new messages recieved since node startup.
 * `Rate`: The per-second rate of new messages over the previous two statsd intervals (available only when graphite integration is enabled).
 * `Connections`: Current number of connected clients.
+* `Delivery`: Messages delivered to consumers in each topology category (zoneLocal, regionLocal, global) over the lifetime of the host by percentage (available only when topology-aware-consumption experiment is enabled in nsqd and messages > 0)
 
 #### Client Connections:
 
 * `Client Host`: Client ID (hostname) and on-hover the connection remote-address.
 * `Protocol`: NSQ protocol version and client user-agent.
-* `Attributes`: TLS and AUTH connection state.
+* `Attributes`: TLS and AUTH connection state, topology category with respect to the nsqd host (zoneLocal, regionLocal, global).
 * `NSQd Host`: Address of the nsqd node this client is connected to.
 * `In-flight`: Current count of messages awaiting response that have been delivered to this client.
 * `Ready Count`: Max number of messages that can be in-flight on this connection. This is controlled by a client's `max_in_flight` setting.
 * `Finished`: Total count of messages that this client has finished (`FIN`).
 * `Requeued`: Total count of messages that this client has requeued (`REQ`).
 * `Messages`: Total count of messages delivered to this client.
+
+If the topology aware consumption experiment is enabled for the nsqd host, client connections in the same zone as the nsqd host will be displayed in green. Client connections in the same region but a different zone as the nsqd host will be displayed in yellow.

_posts/2012-12-01-nsqd.md

@@ -33,6 +33,8 @@ can optionally listen on a third port for HTTPS.
         message processing time percentiles (as float (0, 1.0]) to track (can be specified multiple times or comma separated '1.0,0.99,0.95', default none)
     -e2e-processing-latency-window-time duration
         calculate end to end latency quantiles for this duration of time (ie: 60s would only show quantile calculations from the past 60 seconds) (default 10m0s)
+    -enable-experiment
+        name of an experimental feature to enable (option: topology-aware-consumption)
     -http-address string
         <addr>:<port> to listen on for HTTP clients (default "0.0.0.0:4151")
     -http-client-connect-timeout duration
@@ -109,6 +111,10 @@ can optionally listen on a third port for HTTPS.
         require TLS for client connections (true, false, tcp-https)
     -tls-root-ca-file string
         path to certificate authority file
+    -topology-region
+        region in which nsqd is running, used only if topology-aware-consumption experiment is enabled
+    -topology-zone
+        zone in which nsqd is running, used only if topology-aware-consumption experiment is enabled
     -verbose
         [deprecated] has no effect, use --log-level
     -version