metrics: add debug implementation

Refactor the metrics client slightly to add the concept of a
"reporter" that actually sends the metrics.

The primary implementation is HTTP-based as before, but a key
difference now is that there's another variant that writes to
a file for simplified debugging. This is activated by setting
the `DOCKER_METRICS_DEBUG_LOG` environment variable to a file
path to write events to as JSON lines.

Signed-off-by: Milas Bowman <[email protected]>

Author: milas

cli/main.go

@@ -88,7 +88,7 @@ func init() {
 		panic(err)
 	}
 
-	metricsClient = metrics.NewClient()
+	metricsClient = metrics.NewDefaultClient()
 	metricsClient.WithCliVersionFunc(func() string {
 		return mobycli.CliVersion()
 	})

cli/metrics/client.go

@@ -17,18 +17,18 @@
 package metrics
 
 import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"net"
-	"net/http"
 	"os"
 	"time"
 )
 
+// EnvVarDebugMetricsPath is an optional environment variable used to debug
+// metrics by triggering all events to also be written as JSON lines to the
+// specified file path.
+const EnvVarDebugMetricsPath = "DOCKER_METRICS_DEBUG_LOG"
+
 type client struct {
 	cliversion *cliversion
-	httpClient *http.Client
+	reporter   Reporter
 }
 
 type cliversion struct {
@@ -65,18 +65,33 @@ type Client interface {
 	Track(context string, args []string, status string)
 }
 
-// NewClient returns a new metrics client
-func NewClient() Client {
+// NewClient returns a new metrics client that will send metrics using the
+// provided Reporter instance.
+func NewClient(reporter Reporter) Client {
 	return &client{
 		cliversion: &cliversion{},
-		httpClient: &http.Client{
-			Transport: &http.Transport{
-				DialContext: func(_ context.Context, _, _ string) (net.Conn, error) {
-					return conn()
-				},
-			},
-		},
+		reporter:   reporter,
+	}
+}
+
+// NewDefaultClient returns a new metrics client that will send metrics using
+// the default Reporter configuration, which reports via HTTP, and, optionally,
+// to a local file for debugging. (No format guarantees are made!)
+func NewDefaultClient() Client {
+	httpClient := newHTTPClient()
+
+	var reporter Reporter = NewHTTPReporter(httpClient)
+	if metricsLogPath := os.Getenv(EnvVarDebugMetricsPath); metricsLogPath != "" {
+		if f, err := os.OpenFile(metricsLogPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644); err != nil {
+			panic(err)
+		} else {
+			reporter = NewMuxReporter(
+				NewWriterReporter(f),
+				reporter,
+			)
+		}
 	}
+	return NewClient(reporter)
 }
 
 func (c *client) WithCliVersionFunc(f func() string) {
@@ -86,7 +101,7 @@ func (c *client) WithCliVersionFunc(f func() string) {
 func (c *client) Send(command Command) {
 	result := make(chan bool, 1)
 	go func() {
-		postMetrics(command, c)
+		c.reporter.Heartbeat(command)
 		result <- true
 	}()
 
@@ -97,10 +112,3 @@ func (c *client) Send(command Command) {
 	case <-time.After(50 * time.Millisecond):
 	}
 }
-
-func postMetrics(command Command, c *client) {
-	req, err := json.Marshal(command)
-	if err == nil {
-		_, _ = c.httpClient.Post("http://localhost/usage", "application/json", bytes.NewBuffer(req))
-	}
-}

cli/metrics/conn.go

@@ -0,0 +1,33 @@
+/*
+   Copyright 2022 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package metrics
+
+import (
+	"context"
+	"net"
+	"net/http"
+)
+
+func newHTTPClient() *http.Client {
+	return &http.Client{
+		Transport: &http.Transport{
+			DialContext: func(_ context.Context, _, _ string) (net.Conn, error) {
+				return conn()
+			},
+		},
+	}
+}

cli/metrics/reporter.go

@@ -0,0 +1,99 @@
+/*
+   Copyright 2022 Docker Compose CLI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package metrics
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/http"
+)
+
+// Reporter reports metric events generated by the client.
+type Reporter interface {
+	Heartbeat(cmd Command)
+}
+
+// HTTPReporter reports metric events to an HTTP endpoint.
+type HTTPReporter struct {
+	client *http.Client
+}
+
+// NewHTTPReporter creates a new reporter that will report metric events using
+// the provided HTTP client.
+func NewHTTPReporter(client *http.Client) HTTPReporter {
+	return HTTPReporter{client: client}
+}
+
+// Heartbeat reports a metric for aggregation.
+func (l HTTPReporter) Heartbeat(cmd Command) {
+	entry, err := json.Marshal(cmd)
+	if err != nil {
+		// impossible: cannot fail on controlled input (i.e. no cycles)
+		return
+	}
+
+	resp, _ := l.client.Post(
+		"http://localhost/usage",
+		"application/json",
+		bytes.NewReader(entry),
+	)
+	if resp != nil && resp.Body != nil {
+		_ = resp.Body.Close()
+	}
+}
+
+// WriterReporter reports metrics as JSON lines to the provided writer.
+type WriterReporter struct {
+	w io.Writer
+}
+
+// NewWriterReporter creates a new reporter that will write metrics to the
+// provided writer as JSON lines.
+func NewWriterReporter(w io.Writer) WriterReporter {
+	return WriterReporter{w: w}
+}
+
+// Heartbeat reports a metric for aggregation.
+func (w WriterReporter) Heartbeat(cmd Command) {
+	entry, err := json.Marshal(cmd)
+	if err != nil {
+		// impossible: cannot fail on controlled input (i.e. no cycles)
+		return
+	}
+	entry = append(entry, '\n')
+	_, _ = w.w.Write(entry)
+}
+
+// MuxReporter wraps multiple reporter instances and reports metrics to each
+// instance on invocation.
+type MuxReporter struct {
+	reporters []Reporter
+}
+
+// NewMuxReporter creates a reporter that will report metrics to each of the
+// provided reporter instances.
+func NewMuxReporter(reporters ...Reporter) MuxReporter {
+	return MuxReporter{reporters: reporters}
+}
+
+// Heartbeat reports a metric for aggregation.
+func (m MuxReporter) Heartbeat(cmd Command) {
+	for i := range m.reporters {
+		m.reporters[i].Heartbeat(cmd)
+	}
+}

cli/mobycli/exec.go

@@ -73,7 +73,7 @@ func mustDelegateToMoby(ctxType string) bool {
 
 // Exec delegates to com.docker.cli if on moby context
 func Exec(root *cobra.Command) {
-	metricsClient := metrics.NewClient()
+	metricsClient := metrics.NewDefaultClient()
 	metricsClient.WithCliVersionFunc(func() string {
 		return CliVersion()
 	})

cli/server/server.go

@@ -33,7 +33,7 @@ func New(ctx context.Context) *grpc.Server {
 	s := grpc.NewServer(
 		grpc.ChainUnaryInterceptor(
 			unaryServerInterceptor(ctx),
-			metricsServerInterceptor(metrics.NewClient()),
+			metricsServerInterceptor(metrics.NewDefaultClient()),
 		),
 		grpc.StreamInterceptor(streamServerInterceptor(ctx)),
 	)