update grafanaNet docs

* better sample config that's usable out the box
* minor fixes

docs/grafana-net.md

@@ -1,21 +1,28 @@
 The GrafanaNet route is a special route within carbon-relay-ng.
 
-It converts graphite (carbon) input into metrics2.0 form and submits it to a raintank metrics store.
-**Note: the hosted metrics store is currently not yet a public service.  It can currently only be obtained on demand and for proof of concepts. (get in touch at [email protected] if interested).**
+It converts graphite (carbon) input into metrics2.0 form and submits it to a grafanaCloud metrics store.
+**Note: the hosted metrics store is currently not yet a public service.  Get in touch at [email protected] if interested.**
+
+# The quick way
+
+To get started is just take the sample config, uncomment the grafanaNet line, fill in your baseUrl, key and path to storage-schemas.conf
+and start the relay. That's it!
+
+# The more detailed way
 
 note:
-* it requires a grafana.net api key and a url to the hosted store
+* it requires a grafana.com api key and a url to the hosted store
 * api key should have editor or admin role. (viewer works for now, but will be blocked in the future)
 * it needs to read your graphite storage-schemas.conf to determine which intervals to use
 * but will send your metrics the way you send them.
-  (if you send at odd intervals, or an interval that doesn't match your storage-schemas.conf, that's how we will store it)
+  (if you send at odd intervals, or an interval that doesn't match your storage-schemas.conf, that's how we will store it. so make sure you have this correct)
 * any metric messages that don't validate are filtered out. see the admin ui to troubleshoot if needed.
 
 ## syntax
 
 notes:
 * the double space to separate the route definiton from the endpoint properties
-* by specifying a prefix, sub or regex you can only send a subset of your metrics to grafana.net hosted metrics
+* by specifying a prefix, sub or regex you can only send a subset of your metrics to grafana.com hosted metrics
 
 ```
 addRoute grafanaNet key [prefix/sub/regex]  addr apiKey schemasFile [spool=true/false sslverify=true/false bufSize=int flushMaxNum=int flushMaxWait=int timeout=int]")
@@ -38,7 +45,7 @@ note that the matching is applied to the entire metric line (including key, valu
 other options can appear after the schemasFile, space-separated.
 
 * for schemasFile, see [storage-schemas.conf documentation](http://graphite.readthedocs.io/en/latest/config-carbon.html#storage-schemas-conf)
-* bufSize: 1e7 (10 million)
+* bufSize: how many metrics we can queue up in the route before providing backpressure (default 1e7 i.e. 10 million)
 * flushMaxNum: after this many metrics have queued up, trigger a flush (default 10k)
 * flushMaxWait: after this many milliseconds, trigger a flush (default 500)
 * timeout: after how many milliseconds to consider a request to the hosted metrics to timeout, so that it will retry later (default 2000)
@@ -47,38 +54,3 @@ other options can appear after the schemasFile, space-separated.
 Note that there's only 1 flush worker so you have to check the carbon-relay-ng dashboard (or the log)
 to make sure flushes don't last so long that the buffer fills up.
 In that case, increase the flush values, so that we can flush more data per flush.
-
-## example configuration file
-
-notes:
-* the double space to separate the route definiton from the endpoint properties
-* the instrumentation section sets up the relay to send its own performance metrics into itself. You can provide any graphite addr or an empty address to disable.
-
-```
-instance = "proxy"
-
-max_procs = 2
-
-listen_addr = "0.0.0.0:2003"
-admin_addr = "0.0.0.0:2004"
-http_addr = "0.0.0.0:8083"
-spool_dir = "/var/spool/carbon-relay-ng"
-#one of critical error warning notice info debug
-log_level = "notice"
-# How long to keep track of invalid metrics seen
-# Useful time units are "s", "m", "h"
-bad_metrics_max_age = "24h"
-
-# put init commands here, in the same format as you'd use for the telnet interface
-# note the two spaces after the route key.
-# here's some examples:
-init = [
-     'addRoute sendAllMatch carbon-default  your-actual-graphite-server:2003 spool=true pickle=false',
-     'addRoute grafanaNet grafanaNet  http://localhost:8081/metrics your-grafana.net-api-key /path/to/storage-schemas.conf sslverify=false',
-]
-
-[instrumentation]
-# in addition to serving internal metrics via expvar, you can optionally send em to graphite
-graphite_addr = "localhost:2003"
-graphite_interval = 1000  # in ms
-```

examples/carbon-relay-ng-docker.ini

@@ -29,13 +29,48 @@ validation_level_m20 = "medium"
 validate_order = false
 
 # put init commands here, in the same format as you'd use for the telnet interface
+# here's some examples:
 init = [
+     # a plain carbon route that sends all data to the specified carbon (graphite) server (note the double space)
+     #'addRoute sendAllMatch carbon-default  your-graphite-server:2003 spool=true pickle=false',
+
+     # example route for https://grafana.com/cloud/metrics (note the double space)
+     #'addRoute grafanaNet grafanaNet  your-base-url/metrics your-grafana.net-api-key /path/to/storage-schemas.conf',
+
+     # ignore hosts that don't set their hostname properly via prefix match
+     #'addBlack prefix collectd.localhost',
+
+     # ignore foo.<anything>.cpu.... via regex match
+     #'addBlack regex ^foo\..*\.cpu+',
+
+     # aggregate timer metrics with sums
+     #'addAgg sum ^stats\.timers\.(app|proxy|static)[0-9]+\.requests\.(.*) stats.timers._sum_$1.requests.$2 10 20',
+
+     # aggregate timer metrics with averages
+     #'addAgg avg ^stats\.timers\.(app|proxy|static)[0-9]+\.requests\.(.*) stats.timers._avg_$1.requests.$2 5 10',
+
+     # all metrics with '=' in them are metrics2.0, send to carbon-tagger servic (note the double space)
+     #'addRoute sendAllMatch carbon-tagger sub==  127.0.0.1:2006',
+
+     # send to the first carbon destination that matches the metric (note the double spaces between destinations)
+     #'addRoute sendFirstMatch analytics regex=(Err/s|wait_time|logger)  graphite.prod:2003 prefix=prod. spool=true pickle=true  graphite.staging:2003 prefix=staging. spool=true pickle=true'
 ]
 
+# consume metrics via AMQP
+[amqp]
+amqp_enabled = false
+amqp_host = "localhost"
+amqp_port = 5672
+amqp_user = "guest"
+amqp_password = "guest"
+amqp_vhost = "/graphite"
+amqp_exchange = "metrics"
+
 [instrumentation]
 # in addition to serving internal metrics via expvar, you can send them to graphite/carbon
 # IMPORTANT: setting this to "" will disable flushing, and metrics will pile up and lead to OOM
 # see https://github.com/graphite-ng/carbon-relay-ng/issues/50
 # so for now you MUST send them somewhere. sorry.
+# (Also, the interval here must correspond to your setting in storage-schemas.conf if you use grafana hosted metrics)
 graphite_addr = "localhost:2003"
 graphite_interval = 1000  # in ms

examples/carbon-relay-ng.ini

@@ -33,13 +33,29 @@ validate_order = false
 # put init commands here, in the same format as you'd use for the telnet interface
 # here's some examples:
 init = [
-     'addBlack prefix collectd.localhost',  # ignore hosts that don't set their hostname properly (implicit substring matrch).
-     'addBlack regex ^foo\..*\.cpu+', # ignore foo.<anything>.cpu.... (regex pattern match)
-     'addAgg sum ^stats\.timers\.(app|proxy|static)[0-9]+\.requests\.(.*) stats.timers._sum_$1.requests.$2 10 20',
-     'addAgg avg ^stats\.timers\.(app|proxy|static)[0-9]+\.requests\.(.*) stats.timers._avg_$1.requests.$2 5 10',
-     'addRoute sendAllMatch carbon-default  127.0.0.1:2005 spool=true pickle=false',
-     'addRoute sendAllMatch carbon-tagger sub==  127.0.0.1:2006',  # all metrics with '=' in them are metrics2.0 format for tagger
-     'addRoute sendFirstMatch analytics regex=(Err/s|wait_time|logger)  graphite.prod:2003 prefix=prod. spool=true pickle=true  graphite.staging:2003 prefix=staging. spool=true pickle=true'
+     # a plain carbon route that sends all data to the specified carbon (graphite) server (note the double space)
+     #'addRoute sendAllMatch carbon-default  your-graphite-server:2003 spool=true pickle=false',
+
+     # example route for https://grafana.com/cloud/metrics (note the double space)
+     #'addRoute grafanaNet grafanaNet  your-base-url/metrics your-grafana.net-api-key /path/to/storage-schemas.conf',
+
+     # ignore hosts that don't set their hostname properly via prefix match
+     #'addBlack prefix collectd.localhost',
+
+     # ignore foo.<anything>.cpu.... via regex match
+     #'addBlack regex ^foo\..*\.cpu+',
+
+     # aggregate timer metrics with sums
+     #'addAgg sum ^stats\.timers\.(app|proxy|static)[0-9]+\.requests\.(.*) stats.timers._sum_$1.requests.$2 10 20',
+
+     # aggregate timer metrics with averages
+     #'addAgg avg ^stats\.timers\.(app|proxy|static)[0-9]+\.requests\.(.*) stats.timers._avg_$1.requests.$2 5 10',
+
+     # all metrics with '=' in them are metrics2.0, send to carbon-tagger servic (note the double space)
+     #'addRoute sendAllMatch carbon-tagger sub==  127.0.0.1:2006',
+
+     # send to the first carbon destination that matches the metric (note the double spaces between destinations)
+     #'addRoute sendFirstMatch analytics regex=(Err/s|wait_time|logger)  graphite.prod:2003 prefix=prod. spool=true pickle=true  graphite.staging:2003 prefix=staging. spool=true pickle=true'
 ]
 
 # consume metrics via AMQP
@@ -57,5 +73,6 @@ amqp_exchange = "metrics"
 # IMPORTANT: setting this to "" will disable flushing, and metrics will pile up and lead to OOM
 # see https://github.com/graphite-ng/carbon-relay-ng/issues/50
 # so for now you MUST send them somewhere. sorry.
+# (Also, the interval here must correspond to your setting in storage-schemas.conf if you use grafana hosted metrics)
 graphite_addr = "localhost:2003"
 graphite_interval = 1000  # in ms