Migrate docs from github wiki, and standardise markdown notation

docs/additional_tools.md

@@ -0,0 +1,5 @@
+# Additional Tools
+
+The following are tools you might find useful when using, contributing, or testing statsd.
+
+* [statsd-tg](http://octo.it/statsd-tg) – StatsD traffic generator; generates dummy traffic for load testing (C).

docs/admin_interface.md

@@ -1,21 +1,18 @@
-TCP Stats Interface
-===================
+# TCP Stats Interface
 
 A really simple TCP management interface is available by default on port `8126`
 or overriden in the configuration file. Inspired by the memcache stats approach
 this can be used to monitor a live statsd server.  You can interact with the
 management server by telnetting to port `8126`, the following commands are
 available based on the running server.
 
-Common commands
----------------
+## Common commands
 
 * health [up|down] - a way to get/set the health status of statsd. Alone will get you the current health status. Passing a second command will set the status to the new value. Accepted values are _up_ and _down_.
 * config - a dump of the current configuration
 * quit - close the connection from the server side
 
-Statsd specific commands
-------------------------
+## Statsd specific commands
 
 * stats - some stats about the running server
 * counters - a dump of all the current counters
@@ -64,8 +61,7 @@ The health output:
 * using health up or health down, you can change the current health status.
 * the healthStatus configuration option allows you to set the default health status at start.
 
-Statsd Proxy specific commands
-------------------------------
+## Statsd Proxy specific commands
 
 * status - the status of the current server
 

docs/backend.md

@@ -1,5 +1,4 @@
-Supported Backends
-------------------
+# Supported Backends
 
 StatsD supports pluggable backend modules that can publish
 statistics from the local StatsD daemon to a backend service or data
@@ -30,33 +29,34 @@ giving the relative path (e.g. `./backends/graphite`).
 A robust set of are also available as plugins to allow easy reporting into databases,
 queues and third-party services.
 
-## Available Third-party backends
-- [amqp-backend](https://github.com/mrtazz/statsd-amqp-backend)
-- [atsd-backend](https://github.com/axibase/atsd-statsd-backend)
-- [aws-cloudwatch-backend](https://github.com/camitz/aws-cloudwatch-statsd-backend)
-- [node-bell](https://github.com/eleme/node-bell)
-- [couchdb-backend](https://github.com/sysadminmike/couch-statsd-backend)
-- [datadog-backend](https://github.com/DataDog/statsd-datadog-backend)
-- [elasticsearch-backend](https://github.com/markkimsal/statsd-elasticsearch-backend)
-- [ganglia-backend](https://github.com/jbuchbinder/statsd-ganglia-backend)
-- [hosted graphite backend](https://github.com/hostedgraphite/statsdplugin)
-- [influxdb backend](https://github.com/bernd/statsd-influxdb-backend)
-- [instrumental backend](https://github.com/collectiveidea/statsd-instrumental-backend)
-- [jut-backend](https://github.com/jut-io/statsd-jut-backend)
-- [leftronic backend](https://github.com/sreuter/statsd-leftronic-backend)
-- [librato-backend](https://github.com/librato/statsd-librato-backend)
-- [mongo-backend](https://github.com/dynmeth/mongo-statsd-backend)
-- [monitis backend](https://github.com/jeremiahshirk/statsd-monitis-backend)
-- [mysql backend](https://github.com/fradinni/nodejs-statsd-mysql-backend)
-- [netuitive backend](https://github.com/Netuitive/statsd-netuitive-backend)
-- [opencensus-backend](https://github.com/DazWilkin/statsd-opencensus-backend)
-- [opentsdb backend](https://github.com/emurphy/statsd-opentsdb-backend)
-- [socket.io-backend](https://github.com/Chatham/statsd-socket.io)
-- [stackdriver backend](https://github.com/Stackdriver/stackdriver-statsd-backend)
-- [statsd-backend](https://github.com/dynmeth/statsd-backend)
-- [statsd http backend](https://github.com/bmhatfield/statsd-http-backend)
-- [statsd aggregation backend](https://github.com/wanelo/gossip_girl)
-- [warp10-backend](https://github.com/cityzendata/statsd-warp10-backend)
-- [zabbix-backend](https://github.com/parkerd/statsd-zabbix-backend)
+## Available third-party backends
+
+* [amqp-backend](https://github.com/mrtazz/statsd-amqp-backend)
+* [atsd-backend](https://github.com/axibase/atsd-statsd-backend)
+* [aws-cloudwatch-backend](https://github.com/camitz/aws-cloudwatch-statsd-backend)
+* [node-bell](https://github.com/eleme/node-bell)
+* [couchdb-backend](https://github.com/sysadminmike/couch-statsd-backend)
+* [datadog-backend](https://github.com/DataDog/statsd-datadog-backend)
+* [elasticsearch-backend](https://github.com/markkimsal/statsd-elasticsearch-backend)
+* [ganglia-backend](https://github.com/jbuchbinder/statsd-ganglia-backend)
+* [hosted graphite backend](https://github.com/hostedgraphite/statsdplugin)
+* [influxdb backend](https://github.com/bernd/statsd-influxdb-backend)
+* [instrumental backend](https://github.com/collectiveidea/statsd-instrumental-backend)
+* [jut-backend](https://github.com/jut-io/statsd-jut-backend)
+* [leftronic backend](https://github.com/sreuter/statsd-leftronic-backend)
+* [librato-backend](https://github.com/librato/statsd-librato-backend)
+* [mongo-backend](https://github.com/dynmeth/mongo-statsd-backend)
+* [monitis backend](https://github.com/jeremiahshirk/statsd-monitis-backend)
+* [mysql backend](https://github.com/fradinni/nodejs-statsd-mysql-backend)
+* [netuitive backend](https://github.com/Netuitive/statsd-netuitive-backend)
+* [opencensus-backend](https://github.com/DazWilkin/statsd-opencensus-backend)
+* [opentsdb backend](https://github.com/emurphy/statsd-opentsdb-backend)
+* [socket.io-backend](https://github.com/Chatham/statsd-socket.io)
+* [stackdriver backend](https://github.com/Stackdriver/stackdriver-statsd-backend)
+* [statsd-backend](https://github.com/dynmeth/statsd-backend)
+* [statsd http backend](https://github.com/bmhatfield/statsd-http-backend)
+* [statsd aggregation backend](https://github.com/wanelo/gossip_girl)
+* [warp10-backend](https://github.com/cityzendata/statsd-warp10-backend)
+* [zabbix-backend](https://github.com/parkerd/statsd-zabbix-backend)
 
 [graphite]: https://graphite.readthedocs.io/en/latest/

docs/backend_interface.md

@@ -1,5 +1,4 @@
-Backend Interface
------------------
+# Backend Interface
 
 Backend modules are Node.js [modules][nodemods] that listen for a
 number of events emitted from StatsD. Each backend module should

docs/client_implementations.md

@@ -0,0 +1,108 @@
+# StatsD Clients
+
+A number of clients have been made for pushing metrics into statsd and open sourced by the wider community.
+
+**Node**
+* [lynx](https://github.com/dscape/lynx) — Node.js client used by Mozilla, Nodejitsu, etc.
+* [Node-Statsd](https://github.com/sivy/node-statsd) — Node.js client
+* [node-statsd-client](https://github.com/msiebuhr/node-statsd-client) — Node.js client
+* [node-statsd-instrument](https://github.com/syrio/node-statsd-instrument) — Node.js client
+* [statistik](https://github.com/godmodelabs/statistik) - Node.js client with timers & CLI
+* [statsy](https://github.com/segmentio/statsy) - clean idiomatic statsd client
+
+**Java**
+* [java-statsd-client](https://github.com/youdevise/java-statsd-client) — Lightweight (zero deps) Java client
+* [Statsd over SLF4J](https://github.com/nzjess/statsd-over-slf4j) — Java client with SLF4J logging tie-in
+* [play-statsd](https://github.com/vznet/play-statsd) — Play Framework 2.0 client for Java and Scala
+* [statsd-netty](https://github.com/flozano/statsd-netty) — Netty-based Java 8 client
+
+**Python**
+* [Py-Statsd](https://github.com/sivy/py-statsd) — Server and Client
+* [Python-Statsd](https://github.com/WoLpH/python-statsd) — Python client
+* [pystatsd](https://github.com/jsocol/pystatsd) — Python client
+* [Django-Statsd](https://github.com/WoLpH/django-statsd) — Django client
+
+**Ruby**
+* [statsd-instrument](https://github.com/Shopify/statsd-instrument) — Ruby client
+* [statsd](https://github.com/reinh/statsd/) — Ruby client (needs new maintainer)
+* [Statsd-Client](https://github.com/dawanda/statsd-client) — Ruby client (not maintained)
+
+**Perl**
+* [Net::Statsd](https://github.com/cosimo/perl5-net-statsd) — Perl client, also available on [CPAN](https://metacpan.org/module/Net::Statsd)
+* [Net::StatsD::Client](https://github.com/sivy/statsd-client) — Perl client, not available on CPAN
+* [Etsy::StatsD](https://github.com/sanbeg/Etsy-Statsd) - Perl client, also available on [CPAN] (https://metacpan.org/module/Etsy::StatsD)
+
+**PHP**
+* [Metrics](https://github.com/beberlei/metrics#metrics)
+* [PHP client](https://gist.github.com/1065177/5f7debc212724111f9f500733c626416f9f54ee6)
+* [php-statsd](https://github.com/seejohnrun/php-statsd) and Spark
+* [php-statsd-client](https://github.com/godmodelabs/php-statsd-client) - supports SplClassLoader
+* [statsd-php-client](https://github.com/iFixit/statsd-php-client) - Minimalist performant client
+* [phpLeague-statsd-client](https://github.com/thephpleague/statsd) - Php League StatsD client
+* [statsd-php-client](https://github.com/liuggio/statsd-php-client) - optimized client with monolog and symfony2 integrations available
+* [statsd-php](https://github.com/domnikl/statsd-php) - PSR-4 compatible client
+
+**Clojure**
+* [Clojure client](https://github.com/pyr/clj-statsd)
+
+**Io**
+* [io-statsd](https://github.com/seejohnrun/io-statsd) — StatsD Client for Io
+
+**C**
+* [C client](https://github.com/romanbsd/statsd-c-client) — A trivial C client
+
+**C++**
+* [statsd-client-cpp](https://github.com/talebook/statsd-client-cpp) — StatsD Client in CPP
+* [cpp-statsd-client](https://github.com/vthiery/cpp-statsd-client) — A header-only StatsD client implemented in C++
+
+**.NET**
+* [NStatsD.Client](https://github.com/robbihun/NStatsD.Client) — .NET 4.0 client
+* [C# client](https://github.com/goncalopereira/statsd-csharp-client) — C# client
+* [graphite-client](https://github.com/peschuster/graphite-client) — .NET client library for StatsD and Graphite
+* [StatsC](https://bitbucket.org/pavlos256/statsc) — An asynchronous client with built-in support for batching
+* [JustEat.StatsD](https://github.com/justeat/JustEat.StatsD) — A .NET library for publishing metrics to statsd. Targets both .NET full framework and .NET Standard 2.0.
+
+**Go**
+* [GoE](https://godoc.org/github.com/pascaldekloe/goe/metrics) — Minimal & Performant
+* [go-statsd-client](https://github.com/cactus/go-statsd-client) — Simple Go client
+* [g2s](https://github.com/peterbourgon/g2s)
+* [StatsD](https://github.com/quipo/statsd)
+* [statsd](https://github.com/alexcesaro/statsd) — A simple and very fast StatsD client
+
+**Apache**
+* [mod_statsd](https://github.com/jib/mod_statsd) - StatsD client to send stats straight from [Apache](https://modules.apache.org/)
+
+**Varnish**
+* [libvmod-statsd](https://github.com/jib/libvmod-statsd) - StatsD client to send stats straight from [Varnish](http://varnish-cache.org)
+
+**PowerShell**
+* [powershell-statsd](https://github.com/joehack3r/powershell-statsd) - PowerShell client
+
+**Browser**
+* [StatsC](https://github.com/godmodelabs/statsc) - Push stats to StatsD from the browser!
+* [StatsD HTTP Proxy](https://github.com/sokil/statsd-http-proxy) - HTTP proxy to StatsD with REST interface for using in browsers
+* [StatsD HTTP Client](https://github.com/Molyakos/statsd-http-client) - StatsD client over http for using in browsers
+
+**Objective-C**
+* [MCStatsd](https://github.com/Marketcircle/MCStatsd) - Cocoa client
+
+**ActionScript**
+* [flash-statsd](https://github.com/simongregory/flash-statsd) - Flash client
+
+**WordPress**
+* [wordpress-statsd](https://github.com/uglyrobot/wordpress-statsd) - WordPress Plugin
+
+**Drupal**
+* [StatsD](https://www.drupal.org/project/statsd) - Drupal module
+
+**Haskell**
+* [statsd-client](https://github.com/keithduncan/statsd-client)
+
+**R**
+* [rstatsd](https://github.com/stumpyfr/rstatsd)
+
+**Lua**
+* [lua-statsd](https://github.com/stvp/lua-statsd-client)
+
+**Nim**
+* [statsd_client](https://github.com/FedericoCeratto/nim-statsd-client)

docs/cluster_proxy.md

@@ -1,9 +1,7 @@
-Statsd Cluster Proxy
-==============
+# Statsd Cluster Proxy
 
 Statsd Cluster Proxy is a udp proxy that sits infront of multiple statsd instances.
 
-
 Create a proxyConfig.js file:
 
   `cp exampleProxyConfig.js proxyConfig.js`
@@ -20,8 +18,8 @@ It handles a simple health check that dynamically recalculates the hashring if a
 
 Config Options are documented in the [exampleProxyConfig.js][exampleProxyConfig.js]
 
-Notes
---------------
+## Notes
+
 In your statsd configuration make sure to have the following configuration set: `deleteIdleStats: true`
 
 We plan to remove this restriction in the near future: [#pull/348][pull_348]

docs/graphite.md

@@ -1,5 +1,4 @@
-Configuring Graphite for StatsD 
--------------------------------
+# Configuring Graphite for StatsD
 
 Many users have been confused to see their hit counts averaged, gone missing when
 the data is intermittent, or never stored when statsd is sending at a different

docs/graphite_pickle.md

@@ -1,5 +1,4 @@
-Pickling for Graphite
-=====================
+# Pickling for Graphite
 
 The graphite statsd backend can optionally be configured to use pickle
 for its over-the-wire protocol.
@@ -15,8 +14,7 @@ more CPU processing by the graphite endpoint.
 The message format expected by the graphite pickle endpoint consists
 of a header and payload.
 
-The Payload
------------
+## The Payload
 
 The message payload is a list of tuples. Each tuple contains the measurement
 for a single metric name. The measurement is encoded as a second,
@@ -60,8 +58,7 @@ The trailing `L` for long fields is unnecessary, but we are adding the
 character to match Python pickle output. It's a side-effect of
 `repr(long(1234))`.
 
-The Header
-----------
+## The Header
 
 The message header is a 32-bit integer sent over the wire as
 four-bytes. This integer must describe the length of the pickled

docs/metric_types.md

@@ -1,9 +1,6 @@
-StatsD Metric Types
-==================
+# StatsD Metric Types
 
-
-Counting
---------
+## Counting
 
     gorets:1|c
 
@@ -13,14 +10,13 @@ If the count at flush is 0 then you can opt to send no metric at all for
 this counter, by setting `config.deleteCounters` (applies only to graphite
 backend).  Statsd will send both the rate as well as the count at each flush.
 
-### Sampling
+## Sampling
 
     gorets:1|c|@0.1
 
 Tells StatsD that this counter is being sent sampled every 1/10th of the time.
 
-Timing
-------
+## Timing
 
     glork:320|ms|@0.1
 
@@ -79,8 +75,8 @@ Note:
 histograms, as you can make each bin arbitrarily wide,
 i.e. class intervals of different sizes.
 
-Gauges
-------
+## Gauges
+
 StatsD now also supports gauges, arbitrary values, which can be recorded.
 
     gaugor:333|g
@@ -101,8 +97,8 @@ Note:
 This implies you can't explicitly set a gauge to a negative number
 without first setting it to zero.
 
-Sets
-----
+## Sets
+
 StatsD supports counting unique occurences of events between flushes,
 using a Set to store all occuring events.
 
@@ -111,8 +107,8 @@ using a Set to store all occuring events.
 If the count at flush is 0 then you can opt to send no metric at all for this set, by
 setting `config.deleteSets`.
 
-Multi-Metric Packets
---------------------
+## Multi-Metric Packets
+
 StatsD supports receiving multiple metrics in a single packet by separating them
 with a newline.
 
@@ -130,5 +126,3 @@ scenarios:
   of all the hops in your route.
 
 *(These payload numbers take into account the maximum IP + UDP header sizes)*
-
-

docs/namespacing.md

@@ -1,5 +1,5 @@
-Metric namespacing
--------------------
+# Metric namespacing
+
 The metric namespacing in the Graphite backend is configurable with regard to
 the prefixes. Per default all stats are put under `stats` in Graphite, which
 makes it easier to consolidate them all under one schema. However it is

docs/protocol.md

@@ -0,0 +1,3 @@
+# The StatsD Protocol
+
+Coming soon! Meanwhile, see https://github.com/b/statsd_spec

docs/server.md

@@ -1,5 +1,4 @@
-Supported Servers
-------------------
+# Supported Servers
 
 StatsD supports pluggable server modules that listen for incoming
 metrics.

docs/server_implementations.md

@@ -0,0 +1,18 @@
+# Server Implementations
+
+The following is a list of projects that re-implement statsd, if the the main project isn't for you, perhaps one of these is.
+
+* [brubeck](https://github.com/github/brubeck) - Server in C
+* [clj-statsd-svr](https://github.com/netmelody/clj-statsd-svr) — Clojure server
+* [gographite](https://github.com/amir/gographite) — Server in Go
+* [gostatsd](https://github.com/atlassian/gostatsd) — Server in Go
+* [netdata](https://github.com/firehol/netdata) - Embedded statsd server in the netdata server, in C, with visualization
+* [Net::Statsd::Server](https://github.com/cosimo/perl5-net-statsd-server) — Perl server, also available on [CPAN](https://metacpan.org/module/Net::Statsd::Server)
+* [Py-Statsd](https://github.com/sivy/py-statsd) — Server and Client
+* [Ruby-Statsdserver](https://github.com/fetep/ruby-statsdserver) — Ruby server
+* [statsd-c](https://github.com/jbuchbinder/statsd-c) — Server in C
+* [statsdaemon (bitly)](https://github.com/bitly/statsdaemon) — Server in Go
+* [statsdaemon (vimeo)](https://github.com/vimeo/statsdaemon) — Server in Go
+* [statsdcc](https://github.com/wayfair/statsdcc) - Server in C++
+* [statsdpy](https://github.com/pandemicsyn/statsdpy) — Python/eventlet Server
+* [statsite](https://github.com/armon/statsite.git) — Server in C

docs/server_interface.md

@@ -1,5 +1,4 @@
-Server Interface
------------------
+# Server Interface
 
 Server modules are Node.js [modules][nodemods] that receive metrics for StatsD.
 Each server module should export the following initialization function: