docs: Add the "why-migrate" section to the util-stats docs

RB_ID=709505

finagle-benchmark/src/main/scala/BUILD

@@ -8,6 +8,7 @@ scala_library(name='scala',
     'finagle/finagle-memcachedx',
     'finagle/finagle-ostrich4',
     'finagle/finagle-stats',
+    'finagle/finagle-commons-stats',
     'finagle/finagle-zipkin',
     'finagle/finagle-benchmark/src/main/thrift:thrift-scala',
   ],

finagle-benchmark/src/main/scala/com/twitter/finagle/stats/StatsReceiverBenchmark.scala

@@ -1,6 +1,7 @@
 package com.twitter.finagle.stats
 
 import com.twitter.common.metrics.{Histogram, Metrics}
+import com.twitter.finagle.benchmark.StdBenchAnnotations
 import com.twitter.ostrich.stats.StatsSummary
 import com.twitter.util.events.Sink
 import java.util
@@ -9,7 +10,7 @@ import scala.util.Random
 
 // ./sbt 'project finagle-benchmark' 'run .*StatsReceiverBenchmark.*'
 @Threads(3)
-class StatsReceiverBenchmark {
+class StatsReceiverBenchmark extends StdBenchAnnotations {
   import StatsReceiverBenchmark._
 
   private[this] def newStat(statRecv: StatsReceiver): Stat =
@@ -21,6 +22,8 @@ class StatsReceiverBenchmark {
     stat.add(i)
   }
 
+  // ----- Ostrich ------
+
   @Benchmark
   def newStatOstrich(state: StatsReceiverState): Stat =
     newStat(state.ostrichStatsReceiver)
@@ -29,10 +32,16 @@ class StatsReceiverBenchmark {
   def addOstrich(addState: AddState, state: StatState): Unit =
     add(addState, state.ostrichStat)
 
+  @Benchmark
+  def incrOstrich(state: CounterState): Unit =
+    state.ostrichCounter.incr()
+
   @Benchmark
   def queryOstrich(state: QueryState): StatsSummary =
     state.ostrichGet()
 
+  // ----- Commons Metrics ------
+
   @Benchmark
   def newStatMetricsCommons(state: StatsReceiverState): Stat =
     newStat(state.metricsStatsReceiver)
@@ -41,10 +50,16 @@ class StatsReceiverBenchmark {
   def addMetricsCommons(addState: AddState, state: StatState): Unit =
     add(addState, state.metricsStat)
 
+  @Benchmark
+  def incrMetricsCommons(state: CounterState): Unit =
+    state.metricsCounter.incr()
+
   @Benchmark
   def queryMetricsCommons(state: QueryState): util.Map[String, Number] =
     state.metricsGet()
 
+  // ----- Commons Metrics (Bucketed) ------
+
   @Benchmark
   def newStatMetricsBucketed(state: StatsReceiverState): Stat =
     newStat(state.metricsBucketedStatsReceiver)
@@ -57,6 +72,15 @@ class StatsReceiverBenchmark {
   def queryMetricsBucketed(state: QueryState): util.Map[String, Number] =
     state.metricsBucketedGet()
 
+  // ----- Commons Stats ------
+
+  @Benchmark
+  def addStatsCommons(addState: AddState, state: StatState): Unit =
+    add(addState, state.statsStat)
+
+  @Benchmark
+  def incrStatsCommons(state: CounterState): Unit =
+    state.statsCounter.incr()
 }
 
 object StatsReceiverBenchmark {
@@ -72,6 +96,8 @@ object StatsReceiverBenchmark {
     Sink.default,
     (n: String) => new MetricsBucketedHistogram(n))
 
+  private[this] val stats = new CommonsStatsReceiver
+
   @State(Scope.Benchmark)
   class StatsReceiverState {
     val ostrichStatsReceiver: StatsReceiver = ostrich
@@ -84,6 +110,14 @@ object StatsReceiverBenchmark {
     val ostrichStat: Stat = ostrich.stat("histo")
     val metricsStat: Stat = metrics.stat("histo")
     val metricsBucketedStat: Stat = metricsBucketed.stat("histo")
+    val statsStat: Stat = stats.stat("histo")
+  }
+
+  @State(Scope.Benchmark)
+  class CounterState {
+    val ostrichCounter: Counter = ostrich.counter("cnt")
+    val metricsCounter: Counter = metrics.counter("cnt")
+    val statsCounter: Counter = stats.counter("cnt")
   }
 
   @State(Scope.Thread)

project/Build.scala

@@ -553,6 +553,7 @@ object Finagle extends Build {
     finagleMemcachedX,
     finagleOstrich4,
     finagleStats,
+    finagleCommonsStats,
     finagleZipkin)
 
   lazy val finagleTesters = Project(