author: alexanderh@qualtrics.com

Sending Metrics with `golang/metrics`
===

This guide will walk you through how to configure a Go client to send metrics to the [metrics service](https://odo.corp.qualtrics.com/wiki/index.php/Metrics_As_A_Service).

If you are looking for how to record runtime metrics about your Go application check out the [_____ guide found _____](TODO insert link).

Click here for the [full GoDoc for the golang/metrics package](http://godoc-app.eng.qops.net/gitlab-app.eng.qops.net/golang/metrics).

## Configuring hiera

Each production host has a telegraf agent that accepts statsD UDP packets to be forwarded on to the metrics service. In the hiera confiuration for your app you need to add telegraf to the container's host file and inject the local telegraf address as an environment variable. 

```yaml
docker::apps:
  app:
      ...
      docker_args: >
        --add-host="telegraf:%{::ipaddress}"
        -e STATS_REPORTER_ADDRESS="telegraf:8125"
```

## Using `golang/metrics`

You can use the the package-level `DefaultReporter` or create an instance of a `Reporter` to be passed to you application's types.

### Package-level Reporter

To use the `DefaultReporter` you need to enable it. In your main func, enable the reporter before your app starts. Note that you will use the environment variable that you configured in hiera.

```go
func main() {
	if err := metrics.EnableStatsDReporter(
	    "my_cannonical_service_id",
	    metrics.AddressFromEnv("STATS_REPORTER_ADDRESS"),
	); err != nil {
		fmt.Printf("unable to connect to statsd: %v", err)
	}

	// Ensure that metrics are flushed on shutdown
	defer metrics.DefaultReporter.Close()
}

// Somewhere in the application
metrics.IncCounter("my_request", metrics.Tag("foo", "bar"))
```

!!! warning
    Metrics are buffered before being sent to StatsD. If your application does not close the DefaultReporter before shutdown, some collected metrics may be lost. (In the future, this package's API may be updated to better reflect this.)

Then within your application you can call the other package-level funcs to send metrics.

```go
metrics.IncCounter("my_request", metrics.Tag("foo", "bar"))
// or
defer metrics.NewTimer("http_request", Tag("protocol", "http2")).Record()

```

!!! info
    Note that when `metrics.EnableStatsDReporter` is used to enable the `DefaultReporter` the `golang/http/accesslog` package will use that `DefaultReporter` to send timing metrics of each request handled. The sent `http_request_time` metric will be tagged with `status_code` and `name` (which is the id/name provided by the consumer with `accesslog.SetRequired(ctx, accesslog.Name, ...)`)

### Reporter Instance

To create an instance of a `Reporter` use the constructor.

```go
reporter, err := metrics.NewReporter(
	"my_cannonical_service_id", 
	metrics.AddressFromEnv("STATS_REPORTER_ADDRESS"),
)
if err != nil {
	fmt.Printf("unable to connect to statsd: %v", err)
}
```

Then within your application pass the `reporter` variable to your types and call the methods rather than the package-level funcs.

```go
reporter.IncCounter("my_request", metrics.Tag("foo", "bar"))
// or
defer reporter.NewTimer("http_request", Tag("protocol", "http2")).Record()

```

Now your metrics can be queried in grafana or kairos!