Updated the docs (#71)

Updated the docs

Author: grzkv

README.md

@@ -14,9 +14,23 @@ Build and run
 `go get -u github.com/bookingcom/nanotube`
 2. Navigate to it and run
 `make`
+to build
 3. Run it with
 
-`./nanotube -config config/config.toml
+```
+./nanotube -config config/config.toml
+```
+
+Command line options:
+
+```
+-config string
+    Path to config file.
+-validate
+    Validate configuration files.
+-version
+    Print version info.
+```
 
 Running with docker-compose
 -----------------------------------
@@ -32,7 +46,6 @@ You can feed in sample data with:
 ```
 echo "test1.test 5 $(date +%s)" | nc -c localhost 2003
 ```
-As many netcat implementations exist, a parameter may be needed to instruct it to close the socket once data is sent. Such param will usually be -q0, -c or -N. Refer to your implementation man page.
 
 Get it back with:
 
@@ -45,15 +58,37 @@ To test the second store (alone or in conjunction) change the metric path to `te
 Record structure
 ----------------
 
-The only supported protocol is [line](https://graphite.readthedocs.io/en/latest/feeding-carbon.html#the-plaintext-protocol). The records should follow the structure:
+The only supported protocol is [line](https://graphite.readthedocs.io/en/latest/feeding-carbon.html#the-plaintext-protocol). The records have the structure:
 ```
 path.path.path value datetime
 ```
 
 Config
 ------
 
-Please refer to the sample configs in the _config_ folder for examples and documentation.
+Please refer to the [sample config](config/config.toml) for examples and documentation.
+
+Routing
+-------
+
+Is defined in the [rules config](config/rules.toml) that is in turn referred to in the [main config](config/config.toml). This is how it works:
+- routing rules are applied to each incoming record in order;
+    - if regex in a rule matches, the record is sent to the clusters in the `clusters` list;
+        - if `continue` is `true` continue matching next rules, stop otherwise. `false` is the default;
+    - if regex does not match, continue down the list of rules;
+- multiple rules can be matched to each record;
+- each record can be sent to a single cluster at most once. If two rules send it to same cluster, only one instance will be sent;
+- cluster names must be from the set defined in the [clusters config](clonfig/clusters.toml);
+
+#### Rewrites
+
+Optionally, it is possible to apply the [rewrite rules](config/rewrite.toml). This is how they work:
+
+- rewrites are applied before the routing;
+- all rules are applied to each record one-by-one in order. The record may be modified along the way;
+- rule matches if `from` matches;
+    - then metric path is rewriten to `to` in place;
+    - if `copy` is `true` the original metric is copied and sent directly to be routed skipping the following re-writes. `copy` is `false` be default.
 
 Record validation and normalization
 -----------------------------------
@@ -79,7 +114,7 @@ Tags are not supported for now. See https://github.com/bookingcom/nanotube/issue
 Design
 ------
 
-Please refer to the design doc _docs/design.md_.
+Design details are in the design [doc](docs/design.md).
 
 
 Acknowledgment

config/clusters.toml

@@ -1,27 +1,27 @@
 [[cluster]]
-name = "local0"
-type = "jump" # cluster type defines routing inside a cluster
+name = 'local0'
+type = 'jump' # cluster type defines routing inside a cluster
     [[cluster.hosts]]
-    name = "localhost" # FQDN or IP of the host
+    name = 'localhost' # FQDN or IP of the host
     port = 8001 # optional, overrides setting in main config
     index = 0 # index in the hash ring 
     [[cluster.hosts]]
-    name = "localhost"
+    name = 'localhost'
     port = 8002
     index = 1
 
 [[cluster]]
-name = "local1"
-type = "jump"
+name = 'local1'
+type = 'jump'
     [[cluster.hosts]]
-    name = "localhost"
+    name = 'localhost'
     port = 8101
     index = 0
     [[cluster.hosts]]
-    name = "localhost"
+    name = 'localhost'
     port = 8102
     index = 1
     [[cluster.hosts]]
-    name = "localhost"
+    name = 'localhost'
     port = 8103
     index = 2

config/rewrite.toml

@@ -1,10 +1,17 @@
-# Rewrite rules.
-# - all rules are applied to each record
-# - if rule mathches, metric path is rewriten
-# - if copy is true, new metric is created
+# E.g.
+# In: abcxxx
+# Out: cdexxx
+[[rewrite]]
+    from = 'abc'
+    to = 'cde'
 
+# E.g.
+# In: xxx.A99.foo.bar
+# Out:
+# - xxx.foo.bar.A99
+# - xxx.A99.foo.bar
 [[rewrite]]
- from = "abc"
- to = "cde"
- copy = true
+    from = '^xxx.([A-Za-z0-9_-]+).(.*)'
+    to = 'xxx.$2.$1'
+    copy = true
 

config/rules.toml

@@ -1,25 +1,17 @@
-# Routing rules.
-# - all routing rules are applied to each incoming record;
-# - when regex in the rule matches, the record is sent to the clusters in the "clusters" list;
-# - many rules can be matched to each record;
-# - each record can be sent to a cluster at most once. If two rules send it to same cluster, only one instance will be sent;
-# - cluster names must be from the set defined in the clusters config
-# - Continue is used to signal whether to continue matching next set of rules for a record,
-# - or by default (or when continue is explicitly set to false), stop and move to next record
-
 [[rule]]
     regexs = [
-        ".*a.*"
+        '.*a.*'
     ]
     clusters = [
-        "local0"
+        'local0'
     ]
     continue = true
 
 [[rule]]
     regexs = [
-        ".*b.*"
+        '.*b.*'
     ]
     clusters = [
-        "local1"
+        'local1'
     ]
+

pkg/rewrites/rewrites.go

@@ -77,5 +77,4 @@ func (rw Rewrites) RewriteMetric(record *rec.Rec) []*rec.Rec {
 		}
 	}
 	return result
-
 }

pkg/rewrites/rewrites_test.go

@@ -39,8 +39,8 @@ func TestRewrites(t *testing.T) {
 	}{
 		{
 			rewrites: "first",
-			in:       "abc",
-			out:      []string{"cde"},
+			in:       "abcxxx",
+			out:      []string{"cdexxx"},
 		},
 		{
 			rewrites: "first",