feat: support custom metric types (#45)

Add a `custom()` method where the metric type is passed in by the caller,
to allow using statsd backends that support metric types beyond those
supported by the original Etsy statsd daemon.

Author: dsze

README.md

@@ -134,6 +134,20 @@ One may also attach tags to a metrics, e.g.
 client.gauge("titi", 3.2, 0.1f, {"foo", "bar"});
 ```
 
+### Custom metric types
+
+Some statsd backends (e.g. Datadog, netdata) support metric types beyond those supported by the original Etsy statsd daemon, e.g.
+
+* Histograms (type "h"), which are like Timers, but with different units
+* Dictionaries (type "d"), which are like Sets but also record a count for each unique value
+
+Non-standard metrics can be sent using the `custom()` method, where the metric type is passed in by the caller.  The client performs no validation, under the assumption that the caller will only pass in types, values, and other optional parameters (e.g. frequency, tags) that are supported by their backend.  The templated `value` parameter must support serialization to a `std::basic_ostream` using `operator<<`.
+
+```cpp
+// Record a histogram of packet sizes
+client.custom("packet_size", 1500, "h");
+```
+
 ## Advanced Testing
 
 A simple mock StatsD server can be found at `tests/StatsdServer.hpp`. This can be used to do simple validation of your application's metrics, typically in the form of unit tests. In fact this is the primary means by which this library is tested. The mock server itself is not distributed with the library so to use it you'd need to vendor this project into your project. Once you have though, you can test your application's use of the client like so:

include/cpp-statsd-client/StatsdClient.hpp

@@ -122,6 +122,14 @@ class StatsdClient {
              float frequency = 1.0f,
              const std::vector<std::string>& tags = {}) const noexcept;
 
+    //! Records a custom metric type for the key, with a given value, at a given frequency
+    template <typename T>
+    void custom(const std::string& key,
+                const T value,
+                const char* type,
+                float frequency = 1.0f,
+                const std::vector<std::string>& tags = {}) const noexcept;
+
     //! Seed the RNG that controls sampling
     void seed(unsigned int seed = std::random_device()()) noexcept;
 
@@ -248,6 +256,15 @@ inline void StatsdClient::set(const std::string& key,
     send(key, sum, detail::METRIC_TYPE_SET, frequency, tags);
 }
 
+template <typename T>
+inline void StatsdClient::custom(const std::string& key,
+                                 const T value,
+                                 const char* type,
+                                 const float frequency,
+                                 const std::vector<std::string>& tags) const noexcept {
+    send(key, value, type, frequency, tags);
+}
+
 template <typename T>
 inline void StatsdClient::send(const std::string& key,
                                const T value,

tests/testStatsdClient.cpp

@@ -139,6 +139,11 @@ void testSendRecv(uint64_t batchSize, uint64_t sendInterval) {
         client.count("foo", -42, .9f, {"bar", "baz"});
         throwOnError(client);
         expected.emplace_back("sendRecv.foo:-42|c|@0.90|#bar,baz");
+
+        // Custom metric type should pass through all params
+        client.custom("custom_metric_type", 5678, "cust", .95f, {"tag1", "tag2"});
+        throwOnError(client);
+        expected.emplace_back("sendRecv.custom_metric_type:5678|cust|@0.95|#tag1,tag2");
     }
 
     // Signal the mock server we are done