Add emitting/listening support for metrics over the gRPC protocol (#822)

* Listen for SSF stats over gRPC

* Add emitting metrics over gRPC to veneur-emit

* Fix a couple metrics emitting things

* Add initial emitting of dogstatsd over gRPC

* Minor fixes

* Fix formatting

* Add support for event/service check over gRPC

* Update veneur-emit documentation

* Fix SSL errors when proxying by passing unresolved destination

* Update formatting, comments, and add unit test

* Update wordings and formatting

* Fixing error messages and adding link for fixed race condition

* Update changelog to be WIP

CHANGELOG.md

@@ -1,11 +1,16 @@
+# 14.1.0, (WIP)
+
+## Added
+* The ability to emit dogstatsd metrics from veneur-emit over plain TCP in addition to the current plain UDP. Thanks, [shrivu-stripe](https://github.com/shrivu-stripe)!
+* A config option and health checking for beginning support of emitting/receiving metrics via gRPC. Thanks, [eriwo-stripe](https://github.com/eriwo-stripe)!  
+* A gRPC server that listens for SSF spans and dogstatsd metrics on grpc_listening_addresses. Thanks [eriwo-stripe](https://github.com/eriwo-stripe) and [shrivu-stripe](https://github.com/shrivu-stripe)!
+* The ability to emit metrics from veneur-emit via the gRPC protocol as well as the option to specify a proxy for those metrics. Thanks [eriwo-stripe](https://github.com/eriwo-stripe) and [shrivu-stripe](https://github.com/shrivu-stripe)!
+
 # 14.0.0, 2020-01-14
 
 ## Updated
 * Migrated from dep to Go modules. Clients must now use the updated import path `github.com/stripe/veneur/v14`. Thanks, [andybons](https://github.com/andybons)!
 
-## Added
-* A config option and health checking for beginning support of emitting/receiving metrics via gRPC. Thanks, [eriwo-stripe](https://github.com/eriwo-stripe)!  
-
 # 13.0.0, 2020-01-05
 
 ## Added

cmd/veneur-emit/README.md

@@ -42,20 +42,24 @@ Usage of veneur-emit:
         Add timestamp to the event. Default is the current Unix epoch timestamp.
   -e_title string
         Title of event. Ex: 'An exception occurred' *
+  -error
+        Mark the reported span as having errored
   -gauge float
         Report a 'gauge' metric. Value must be float64.
+  -grpc
+        Sets the emitting protocal to gRPC. This cannot be used with "udp" hostports.
   -hostport string
         Address of destination (hostport or listening address URL).
   -indicator
         Mark the reported span as an indicator span
-  -error
-        Mark the reported span as having errored
   -mode string
         Mode for veneur-emit. Must be one of: 'metric', 'event', 'sc'. (default "metric")
   -name string
         Name of metric to report. Ex: 'daemontools.service.starts'
   -parent_span_id int
         ID of the parent span.
+  -proxy string
+        Address or URL to be used for proxying gRPC requests. The request will be sent to the proxy with the "hostport" attached so the proxy can forward the request. This can only be used with the "-grpc" flag.
   -sc_hostname string
         Add hostname to the event.
   -sc_msg string
@@ -94,6 +98,59 @@ instance.
 
 ## Dogstatsd mode
 
+### Dogstatsd Protocols
+
+We currently support **TCP** `(tcp://)`, **UDP** `(udp://)`, **Unix Socket** `(unix://)`, and **gRPC** `(tcp://)` protocols for emitting in dogstatsd. 
+
+#### UDP protocol:
+
+We support the UDP protocol as part of the `-hostport` argument. This is the default for hostports that don't provide a protocol.
+
+**Example command:**
+
+```sh
+veneur-emit -hostport udp://127.0.0.1:8200 -name ...
+```
+
+**Example command without specified protocol (uses UDP default):**
+```sh
+veneur-emit -hostport 127.0.0.1:8200 -name ...
+```
+
+#### TCP protocol:
+
+We support the TCP protocol as part of the `-hostport` argument.
+
+**Example command:**
+
+```sh
+veneur-emit -hostport tcp://127.0.0.1:8200 -name ...
+```
+
+#### Unix Socket protocol:
+
+We support Unix Sockets as part of the `-hostport` argument.
+
+**Example command:**
+
+```sh
+veneur-emit -hostport unix:///var/run/veneur/dogstats.sock -name ...
+```
+
+#### gRPC protocol:
+
+We support the gRPC protocol through the `-grpc` flag. When this flag is provided, the `-hostport` argument is treated as the URI of a Veneur instance serving gRPC requests.
+
+**Example command:**
+
+```sh
+veneur-emit -hostport tcp://127.0.0.1:8200 -grpc -name ...
+```
+
+### Dogstatsd Examples
+
+All of the below commands can be used with the `-grpc` flag to send them over gRPC.
+
 Increment a counter in dogstatsd mode:
 
 ```sh
@@ -128,7 +185,48 @@ veneur-emit -hostport udp://127.0.0.1:8200 -name some.set.metric -set customer_a
 
 In SSF mode, veneur-emit will construct and submit an SSF span with
 optional metrics. SSF mode does not yet support events or service
-checks.
+checks. SSF mode is not the default and needs to be enabled by providing the `-ssf` flag.
+
+### SSF Protocols
+
+Currently we support **UDP** `(udp://)`, **Unix Socket** `(unix://)`, and **gRPC** `(tcp://)` protocols for emitting in SSF.
+
+### UDP protocol:
+
+We support the UDP protocol as part of the `-hostport` argument. This is the default for hostports that don't provide a protocol.
+
+**Example command:**
+
+```sh
+veneur-emit -ssf -hostport udp://127.0.0.1:8200 -name ...
+```
+
+**Example command without specified protocol (uses UDP default):**
+```sh
+veneur-emit -ssf -hostport 127.0.0.1:8200 -name ...
+```
+
+#### Unix Socket protocol:
+
+We support Unix Sockets as part of the `-hostport` argument.
+
+**Example command:**
+
+```sh
+veneur-emit -ssf -hostport unix:///var/run/veneur/ssf.sock -name ....
+```
+
+#### gRPC protocol:
+
+We support the gRPC protocol through the `-grpc` flag. When this flag is provided, we treat the `-hostport` argument as a TCP address or URL for the underlying gRPC connection.
+
+**Example command:**
+
+```sh
+veneur-emit -ssf -hostport tcp://127.0.0.1:8200 -grpc -name ...
+```
+
+### SSF Examples
 
 Increment a counter in SSF mode:
 
@@ -157,3 +255,23 @@ were passed in:
 ```sh
 veneur-emit -ssf -hostport unix:///var/run/veneur/ssf.sock -name some.command.timer -command not_a_real_command
 ```
+
+## gRPC
+
+[gRPC](https://grpc.io/) is protocol for making remote service calls. In Veneur we use this to support emitting/receiving metrics over HTTP. 
+More details about our support of gRPC can be found below:
+
+### Supported Modes
+
+We currently support all emitting modes over gRPC. This means dogstatsd (metrics, events, service checks) and ssf spans. 
+To enable gRPC, just add the `-grpc` flag to a command and it will send with the gRPC protocol. 
+NOTE that gRPC uses TCP as its underlying protocol which makes it incompatible with UDP addresses.
+
+### Specifying a Proxy
+
+When using gRPC, you can also specify a proxy address/URL with the `-proxy` argument. 
+When you provide a proxy address, Veneur will send the request to the proxy and attach the `-hostport` argument so the proxy can forward the request.
+The [go http proxy](https://golang.org/pkg/vendor/golang.org/x/net/http/httpproxy/) is an example of a supported proxy.
+Unix Sockets, TCP addresses, and URLs are supported values for the proxy arguments.
+
+