Documentation updates. [skip ci]

- CreateMetric
- PopulateFromEnum
- Updated MetricGroup examples.

Author: bretcope

README.md

@@ -25,7 +25,7 @@ var collector = new MetricsCollector(new BosunOptions()
 Create a counter with only the default tags:
 
 ```csharp
-var counter = collector.GetMetric<Counter>("my_counter", "units", "description");
+var counter = collector.CreateMetric<Counter>("my_counter", "units", "description");
 ```
 
 Increment the counter by 1:

docs/MetricGroup.md

@@ -1,20 +1,32 @@
 # MetricGroup
 
-Because one of the goals of BosunReporter.NET is to encourage using tags to differentiate subsets of the same data (instead of separate metric names), metric groups are built into the library. A metric group is a collection of metrics with the same name, but with different tag values. For example, let's say we have a counter which counts every request. We might want to tag this counter to indicate how many requests were successful versus how many encountered an error. Start by creating a class for our counter, as usual.
+Because one of the goals of BosunReporter.NET is to encourage using tags to differentiate subsets of the same data (instead of separate metric names), metric groups are built into the library. A metric group is a collection of metrics with the same name, but with different tag values. For example, let's say we have a counter which counts every request. We might want to tag this counter to indicate how many requests were successful versus how many encountered an error.
+
+Let's start by defining an enum of the result types we want to track.
+
+```csharp
+public enum Result
+{
+	Error,
+	Success
+}
+```
+
+Then we'll create a class for our counter.
 
 ```csharp
-public RequestCounter : Counter
+public class RequestCounter : Counter
 {
 	[BosunTag]
-	public readonly string Result;
+	public readonly Result Result;
 	public RequestCounter(string result) { Result = result; }
 }
 ```
 
-Now, instead of manually creating a metric for each of the result values we want ("success", "error", etc), we can simply create a group which will enable us to create those metrics implicitly.
+Now, instead of manually creating a metric for each of the result values we want (Success and Error), we can simply create a group which will enable us to create those metrics implicitly.
 
 ```csharp
-var requestCounter = collector.GetMetricGroup<string, RequestCounter>(
+var requestCounter = collector.GetMetricGroup<Result, RequestCounter>(
                                 "requests",                            // name
                                 "requests",                            // unit
                                 "A count of the number of requests",   // description
@@ -23,21 +35,18 @@ var requestCounter = collector.GetMetricGroup<string, RequestCounter>(
 // MetricGroup.Add() creates a metric if it does not already exist, and returns that metric.
 // Best-practice is to call Add() as close to application-startup as possible to avoid 
 // "Unknown" Bosun alerts.
-requestCounter.Add("success");
-requestCounter.Add("error");
-
-...
+requestCounter.Add(Result.Success);
+requestCounter.Add(Result.Error);
 
-// as long as Add() has been previously called for each tag value, you can use indexer syntax
-if (error == null)
-	requestCounter["success"].Increment();
-else
-	requestCounter["error"].Increment();
+// once they've been added, we can use indexer syntax to access those metrics. For example...
+requestCounter[Result.Success].Increment();
 ```
 
-Note that we used the generic type arguments `<string, RequestCounter>` in the example above. This determines the signature of the factory, which is `Func<string, RequestCounter>` in this example because it takes a single string argument, and returns a `RequestCounter`. It also determines the method signature of `Add()`.
+Note that we used the generic type arguments `<Result, RequestCounter>` in the example above. This determines the signature of the factory, which is `Func<Result, RequestCounter>` in this example because it takes a single `Result` argument, and returns a `RequestCounter`. It also determines the method signature of `Add()`.
 
-> Because `RequestCounter` has a constructor which matches the type signature provided (accepts a single string, and returns an instance of RequestCounter), we could have omitted the factory argument. The metric group will use that constructor to generate a default factory.
+> Because `RequestCounter` has a constructor which matches the type signature provided (accepts a single Result, and returns an instance of RequestCounter), we could have omitted the factory argument. The metric group will use that constructor to generate a default factory.
+
+## Multiple Tags
 
 You can also create metric groups which is differentiated by more than one tag (MetricGroup currently supports up to 5, though splitting on more than 2 or 3 may be a code-smell). Simply add additional type arguments to the MetricGroup generic type constructor. Let's use a three-tag counter as an example:
 
@@ -46,13 +55,13 @@ public ThreeTagCounter : Counter
 {
 	[BosunTag] public readonly string One;
 	[BosunTag] public readonly string Two;
-	[BosunTag] public readonly string Three;
+	[BosunTag] public readonly SomeEnum Three;
 
 	public ThreeTagCounter(string one, int two, SomeEnum three)
 	{
 		One = one;
 		Two = two.ToString();
-		Three = three.ToString();
+		Three = three;
 	}
 }
 ```
@@ -85,4 +94,21 @@ helloGroup.Add(2, SomeEnum.MyValue).Increment();
 helloGroup.Add(7, SomeEnum.AnotherValue).Increment();
 ```
 
-> Value types or strings are always best for the metric group arguments. Objects are okay as long as they play well as dictionary keys or values inside a Tuple which is used as a dictionary key. This generally means any object used as a metric group argument should implement IEquatable<T> and have a good GetHashCode implementation.
+> Value types or strings are always best for the metric group arguments. Objects are okay as long as they play well as dictionary keys or values inside a Tuple which is used as a dictionary key. This generally means any object used as a metric group argument should implement IEquatable<T> and have a good GetHashCode implementation.
+
+## Auto-Populate from Enum Values
+
+In the first example, we populated all of the values of our `Result` enum into the group using:
+
+```csharp
+requestCounter.Add(Result.Success);
+requestCounter.Add(Result.Error);
+```
+
+Since it's very common to want one metric per enum value, there is a helper method which does just that. The code below is functionally equivalent to the code above.
+
+```csharp
+requestCounter.PopulateFromEnum();
+```
+
+However, this helper method is only available when there is only one input type parameter, and that type parameter is an enum type. For example, you could use `PopulateFromEnum` on a group with the type signature `MetricGroup<SomeEnum, SomeMetric>`, but not on `MetricGroup<SomeEnum, int, SomeMetric>` because it has more than one input type parameter (`SomeEnum` and `int`).

docs/MetricTypes.md

@@ -9,7 +9,7 @@ Counters are for _counting_ things. The most common use case is to increment a c
 This is the basic counter type. It uses a `long` value and calls `Interlocked.Add()` internally to incrementing the value.
 
 ```csharp
-var counter = collector.GetMetric<Counter>("my_counter", "units", "description");
+var counter = collector.CreateMetric<Counter>("my_counter", "units", "description");
 
 // increment by 1
 counter.Increment();
@@ -24,7 +24,7 @@ A snapshot counter is useful when you only care about updating the counter once
 
 ```csharp
 var count = 0;
-collector.GetMetric("name", "unit", "desc", new SnapshotCounter(() => count++));
+collector.CreateMetric("name", "unit", "desc", new SnapshotCounter(() => count++));
 ```
 
 ## Gauges
@@ -36,7 +36,7 @@ Gauges describe a measurement at a point in time. A good example would be measur
 These are great for metrics where you want to record snapshots of a value, like CPU or memory usage. Pretend we have a method called `GetMemoryUsage` which returns a double. Now, let's write a snapshot gauge which calls that automatically at every metrics reporting interval.
 
 ```csharp
-collector.GetMetric("memory_usage", units, desc, new SnapshotGauge(() => GetMemoryUsage()));
+collector.CreateMetric("memory_usage", units, desc, new SnapshotGauge(() => GetMemoryUsage()));
 ```
 
 That's it. There's no reason to even assign the gauge to a variable.
@@ -48,7 +48,7 @@ That's it. There's no reason to even assign the gauge to a variable.
 These are ideal for low-volume event-based data where it's practical to send all of the data points to Bosun. If you have a measurable event which occurs once every few seconds, then, instead of aggregating, you may want to use an event gauge. Every time you call `.Record()` on an event gauge, the metric will be serialized and queued. The queued metrics will be sent to Bosun on the normal reporting interval, like all other metrics.
 
 ```csharp
-var myEvent = collector.GetMetric<EventGauge>("my_event", units, desc);
+var myEvent = collector.CreateMetric<EventGauge>("my_event", units, desc);
 someObject.OnSomeEvent += (sender, e) => myEvent.Record(someObject.Value);
 ```
 
@@ -89,7 +89,7 @@ public class RouteTimingGauge : AggregateGauge
 Then, instantiate the gauge for our route, and record timings to it.
 
 ```csharp
-var testRouteTiming = collector.GetMetric(
+var testRouteTiming = collector.CreateMetric(
                                           "route_tr",
                                           units,
                                           desc,
@@ -112,7 +112,7 @@ A sampling gauge simply reports the last recorded value at every reporting inter
 If the last recorded value is `Double.NaN`, then nothing will be reported to Bosun.
 
 ```csharp
-var sampler = collector.GetMetric<SamplingGauge>("my_sampler", units, desc);
+var sampler = collector.CreateMetric<SamplingGauge>("my_sampler", units, desc);
 sampler.Record(1.2);
 ```
 

docs/Tags.md

@@ -25,24 +25,24 @@ public class RouteCounter : Counter
 And then let's instantiate one.
 
 ```csharp
-var testRouteOkCounter = collector.GetMetric(
-                                             "hits",
-                                             "units",
-                                             "description",
+var testRouteOkCounter = collector.CreateMetric(
+                                             "hits",          // metric name
+                                             "http requests", // units
+                                             "description",   // meaningful description
                                              new RouteCounter("Test/Route", true));
 ```
 
 The metric name `hits` has now been bound to the `RouteCounter` type. If we try to use that metric name with any other type, the library will throw an exception. However, we can use that metric name with as many different instances of `RouteCounter` as we'd like. For example:
 
 ```csharp
-var testRouteErrorCounter = collector.GetMetric(
+var testRouteErrorCounter = collector.CreateMetric(
                                                 "hits",
                                                 "units",
                                                 "description",
                                                 new RouteCounter("Test/Route", false));
 ```
 
-It it worth noting that the `GetMetric()` method is idempotent, so you'll never end up with duplicate metrics.
+It is worth noting that `CreateMetric()` will throw an exception if you try to create a duplicate metric. That behavior is generally desirable since multiple attempts to create the same metric likely represent a mistake. However, there is also a `GetMetric()` method (with identical signatures) which is idempotent. It still won't allow you to create duplicate metrics, but instead of throwing an exception if an identical metric already exists, it will return the existing metric.
 
 ```csharp
 var one = collector.GetMetric("hits", units, desc, new RouteCounter("Test/Route", true));
@@ -51,6 +51,6 @@ var two = collector.GetMetric("hits", units, desc, new RouteCounter("Test/Route"
 Console.WriteLine(one == two); // outputs True
 ```
 
-This, like the rest of the library, is thread safe. You could use this method to always instantiate and use metrics on-demand. Although, if you're concerned with performance, it is computationally cheaper to store the metrics in variables or a hash rather than calling `GetMetric()` every time you need it.
+This, like the rest of the library, is thread safe. You _could_ use this method to always instantiate and use metrics on-demand. However, if you care about performance or allocations, it is cheaper to store the metrics in variables or a hash rather than calling `GetMetric()` every time you need it. Or even better, consider using a [Metric Group](https://github.com/bretcope/BosunReporter.NET/blob/master/docs/MetricGroup.md) to create your metrics.
 
-This `RouteCounter` type we just created, and any other BosunMetric type, can be used with as many metric names as you'd like. __You don't have to create a class for every metric you use__ if they share common tag lists. In fact, using common tag lists is a great idea which will help encourage consistency in your metrics conventions.
+> This `RouteCounter` type we just created, and any other BosunMetric type, can be used with as many metric names as you'd like. __You don't have to create a class for every metric you use__ if they share common tag lists. In fact, using common tag lists is a great idea which will help encourage consistency in your metrics conventions.