Metrics service docs (#409)

Doc PR for Envoy implementation PR envoyproxy/envoy#2323
Signed-off-by: Rama <ramaraochavali@gmail.com>

api/BUILD

@@ -333,6 +333,7 @@ proto_library(
         ":cds",
         ":eds",
         ":lds",
+        ":metrics",
         ":protocol",
         ":rds",
         ":rls",

api/metrics_service.proto

@@ -2,6 +2,8 @@ syntax = "proto3";
 
 // [#proto-status: draft]
 
+// [#protodoc-title: Metrics Service]
+
 package envoy.api.v2;
 
 import "api/base.proto";
@@ -29,16 +31,16 @@ message StreamMetricsMessage {
     Node node = 1 [(validate.rules).message.required = true];
   }
 
-  // Identifier data effectively is a structured metadata.
+  // Identifier data effectively is a structured metadata. As a performance optimization this will
-  // As a performance optimization this will only be sent in the first message on the stream.
+  // only be sent in the first message on the stream.
   Identifier identifier = 1;
 
   // A list of metric entries
   repeated io.prometheus.client.MetricFamily envoy_metrics = 2;
 }
 
-// Configuration structure for Metrics Service. It is a :ref: `StatsSink <envoy_api_msg_StatsSink>`
+// Metrics Service is configured as a built-in *envoy.metrics_service* :ref:`StatsSink
-// opaque configuration that will be used to create Metrics Service.
+// <envoy_api_msg_StatsSink>`. This opaque configuration will be used to create Metrics Service.
 message MetricsServiceConfig {
   // The upstream gRPC cluster that hosts the metrics service.
   GrpcService grpc_service = 1 [(validate.rules).message.required = true];

api/stats.proto

@@ -15,11 +15,11 @@ import "validate/validate.proto";
 // Configuration for pluggable stats sinks.
 message StatsSink {
   // The name of the stats sink to instantiate. The name must match a supported
-  // stats sink. *envoy.statsd* is a built-in sink suitable for emitting to
+  // stats sink. The built-in stats sinks are:
-  // `statsd <https://github.com/etsy/statsd>`_. Any other built-in stats sink
+  //
-  // can be found in `well_known_names.h
+  // * :ref:`envoy.statsd <envoy_api_msg_StatsdSink>`
-  // <https://github.com/envoyproxy/envoy/blob/master/source/common/config/well_known_names.h>`_
+  // * :ref:`envoy.dog_statsd <envoy_api_msg_DogStatsdSink>`
-  // in the Envoy repository.
+  // * :ref:`envoy.metrics_service <envoy_api_msg_MetricsServiceConfig>`
   string name = 1;
 
   // Stats sink specific configuration which depends on the sink being

docs/build.sh

@@ -36,6 +36,7 @@ PROTO_RST="
   /api/grpc_service/api/grpc_service.proto.rst
   /api/health_check/api/health_check.proto.rst
   /api/lds/api/lds.proto.rst
+  /api/metrics/api/metrics_service.proto.rst
   /api/rds/api/rds.proto.rst
   /api/rls/api/rls.proto.rst
   /api/sds/api/sds.proto.rst

docs/root/api-v2/api.rst

@@ -17,6 +17,7 @@ v2 API reference
   rds.proto
   sds.proto
   stats.proto
+  metrics_service.proto
   trace.proto
   base.proto
   address.proto