util-stats: Add APIs for providing descriptions

Problem/Solution

Add metric description APIs in StatsReceiver and hydrate some key indicators.

JIRA Issues: CSL-9962

Differential Revision: https://phabricator.twitter.biz/D615481

Author: yufangong

CHANGELOG.rst

@@ -6,6 +6,10 @@ Note that ``PHAB_ID=#`` and ``RB_ID=#`` correspond to associated messages in com
 
 Unreleased
 ----------
+New Features
+~~~~~~~~~~~~
+
+* util-stats: Counter, Gauge, and Stat can be instrumented with descriptions. ``PHAB_ID = D615481``
 
 New Features
 ~~~~~~~~~~~~

util-stats/src/main/scala/com/twitter/finagle/stats/StatsReceiver.scala

@@ -125,13 +125,32 @@ trait StatsReceiver {
   @varargs
   def counter(name: String*): Counter = counter(Verbosity.Default, name: _*)
 
+  /**
+   * Get a [[Counter counter]] with the given `description` and `name`.
+   */
+  @varargs
+  def counter(description: Some[String], name: String*): Counter =
+    counter(description.get, Verbosity.Default, name: _*)
+
   /**
    * Get a [[Counter counter]] with the given `name`.
    */
   @varargs
   def counter(verbosity: Verbosity, name: String*): Counter =
     counter(this.metricBuilder(CounterType).withVerbosity(verbosity).withName(name: _*))
 
+  /**
+   * Get a [[Counter counter]] with the given `description` and `name`.
+   */
+  @varargs
+  def counter(description: String, verbosity: Verbosity, name: String*): Counter =
+    counter(
+      this
+        .metricBuilder(CounterType)
+        .withVerbosity(verbosity)
+        .withName(name: _*)
+        .withDescription(description))
+
   /**
    * Get a [[Counter counter]] with the given schema.
    */
@@ -143,13 +162,32 @@ trait StatsReceiver {
   @varargs
   def stat(name: String*): Stat = stat(Verbosity.Default, name: _*)
 
+  /**
+   * Get a [[Stat stat]] with the given `description` and `name`.
+   */
+  @varargs
+  def stat(description: Some[String], name: String*): Stat =
+    stat(description.get, Verbosity.Default, name: _*)
+
   /**
    * Get a [[Stat stat]] with the given name.
    */
   @varargs
   def stat(verbosity: Verbosity, name: String*): Stat =
     stat(this.metricBuilder(HistogramType).withVerbosity(verbosity).withName(name: _*))
 
+  /**
+   * Get a [[Stat stat]] with the given `description` and `name`.
+   */
+  @varargs
+  def stat(description: String, verbosity: Verbosity, name: String*): Stat =
+    stat(
+      this
+        .metricBuilder(HistogramType)
+        .withVerbosity(verbosity)
+        .withName(name: _*)
+        .withDescription(description))
+
   /**
    * Get a [[Stat stat]] with the given schema.
    */
@@ -203,6 +241,12 @@ trait StatsReceiver {
    */
   def addGauge(name: String*)(f: => Float): Gauge = addGauge(Verbosity.Default, name: _*)(f)
 
+  /**
+   * Add the function `f` as a [[Gauge gauge]] with the given name and description.
+   */
+  def addGauge(description: Some[String], name: String*)(f: => Float): Gauge =
+    addGauge(description.get, Verbosity.Default, name: _*)(f)
+
   /**
    * Add the function `f` as a [[Gauge gauge]] with the given name.
    *
@@ -225,6 +269,15 @@ trait StatsReceiver {
   def addGauge(verbosity: Verbosity, name: String*)(f: => Float): Gauge =
     addGauge(this.metricBuilder(GaugeType).withVerbosity(verbosity).withName(name: _*))(f)
 
+  /**
+   * Add the function `f` as a [[Gauge gauge]] with the given name and description.
+   */
+  def addGauge(description: String, verbosity: Verbosity, name: String*)(f: => Float): Gauge =
+    addGauge(
+      this
+        .metricBuilder(GaugeType).withVerbosity(verbosity).withName(name: _*).withDescription(
+          description))(f)
+
   /**
    * Just like $AddGaugeScaladocLink but optimized for better Java experience.
    */