feat: add anonymous execution telemetry

Makefile

@@ -29,7 +29,8 @@ VERSION_VARIABLES := -X $(MODULEPATH)/pkg/manager/context.OCI=$(IMG) \
 	-X $(MODULEPATH)/pkg/integrations/cirrus.version=$(CIRRUS_CLI) \
 	-X $(MODULEPATH)/pkg/integrations/github.runnerVersion=$(GITHUB_RUNNER) \
 	-X $(MODULEPATH)/pkg/integrations/gitlab.version=$(GITLAB_RUNNER) \
-	-X $(MODULEPATH)/pkg/integrations/otelcol.version=$(OTELCOL_VERSION)
+	-X $(MODULEPATH)/pkg/integrations/otelcol.version=$(OTELCOL_VERSION) \
+	-X $(MODULEPATH)/pkg/telemetry.version=$(VERSION)
 LDFLAGS := $(VERSION_VARIABLES) ${GO_EXTRA_LDFLAGS}
 GCFLAGS := all=-N -l
 GOOS := $(shell go env GOOS)

README.md

@@ -197,6 +197,14 @@ mapt --help
 
 ---
 
+## Telemetry
+
+mapt collects anonymous usage statistics to understand adoption: the command path, mapt version, operating system, architecture, and a random installation ID. The data is used only for aggregate statistics and nothing else. mapt does not send command arguments, logs, personal identifiers, or cloud details. A one-time notice is printed on the first run.
+
+Telemetry is enabled by default. To opt out, pass `--no-telemetry` or set `MAPT_TELEMETRY=0` or `DO_NOT_TRACK=1` — set the variable in your shell profile to make it permanent, or set `"enabled": false` in `~/.mapt/telemetry.json` to opt out via config file. Deleting that file resets your installation ID.
+
+---
+
 ## State management
 
 mapt uses [Pulumi](https://www.pulumi.com/) under the hood. Stack state is stored at `--backed-url`:

cmd/mapt/cmd/root.go

@@ -8,6 +8,7 @@ import (
 	"github.com/redhat-developer/mapt/cmd/mapt/cmd/gcp"
 	"github.com/redhat-developer/mapt/cmd/mapt/cmd/ibmcloud"
 	"github.com/redhat-developer/mapt/cmd/mapt/cmd/params"
+	"github.com/redhat-developer/mapt/pkg/telemetry"
 	"github.com/redhat-developer/mapt/pkg/util/logging"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
@@ -16,6 +17,7 @@ import (
 	"path/filepath"
 	"strings"
 	"syscall"
+	"time"
 )
 
 const (
@@ -27,8 +29,12 @@ const (
 )
 
 var (
-	baseDir = filepath.Join(os.Getenv("HOME"), ".mapt")
-	logFile = "mapt.log"
+	baseDir           = filepath.Join(os.Getenv("HOME"), ".mapt")
+	logFile           = "mapt.log"
+	noTelemetryFlag   bool
+	telemetryClient   = telemetry.New(filepath.Join(baseDir, "telemetry.json"))
+	telemetryDecision telemetry.Decision
+	telemetryDone     <-chan struct{}
 )
 
 var rootCmd = &cobra.Command{
@@ -48,9 +54,25 @@ var rootCmd = &cobra.Command{
 
 func runPrerun(cmd *cobra.Command) error {
 	logging.InitLogrus(baseDir, logFile)
+	decision, err := telemetryClient.Resolve(telemetry.ReadOverrides(noTelemetryFlag), cmd.CommandPath(), telemetryCounted(cmd))
+	if err != nil {
+		logging.Debugf("telemetry decision unavailable: %v", err)
+		telemetryDecision = telemetry.Decision{}
+		return nil
+	}
+	telemetryDecision = decision
 	return nil
 }
 
+// telemetryCounted reports whether running this command counts as usage.
+// attachMiddleware only wraps leaf commands that have a RunE, and generated or
+// telemetry-management commands are excluded, so the consent prompt must match
+// exactly that set: prompting for a command that is never counted would ask
+// for consent and give nothing in return.
+func telemetryCounted(cmd *cobra.Command) bool {
+	return !cmd.HasSubCommands() && cmd.RunE != nil && !isExcludedTelemetryCommand(cmd.CommandPath())
+}
+
 func runRoot() {
 	fmt.Println("No command given")
 }
@@ -60,6 +82,7 @@ func init() {
 	flagSet := pflag.NewFlagSet(commandName, pflag.ExitOnError)
 	params.AddDebugFlags(flagSet)
 	rootCmd.PersistentFlags().AddFlagSet(flagSet)
+	rootCmd.PersistentFlags().BoolVar(&noTelemetryFlag, "no-telemetry", false, "Disable anonymous usage statistics for this run")
 	// Subcommands
 	rootCmd.AddCommand(
 		aws.GetCmd(),
@@ -97,10 +120,30 @@ func attachMiddleware(names []string, cmd *cobra.Command) {
 func executeWithLogging(fullCmd string, input func(cmd *cobra.Command, args []string) error) func(cmd *cobra.Command, args []string) error {
 	return func(cmd *cobra.Command, args []string) error {
 		logging.Debugf("running '%s'", fullCmd)
-		return input(cmd, args)
+		err := input(cmd, args)
+		if telemetryDecision.Enabled && !isExcludedTelemetryCommand(fullCmd) {
+			telemetryDone = telemetryClient.Emit(telemetry.Event{
+				InstallID: telemetryDecision.InstallID,
+				Version:   telemetry.Version(),
+				Command:   fullCmd,
+			})
+		}
+		return err
 	}
 }
 
 func runPostrun() {
+	telemetryClient.Wait(telemetryDone, 2*time.Second)
+	telemetryDone = nil
 	logging.CloseLogging()
 }
+
+func isExcludedTelemetryCommand(commandPath string) bool {
+	for _, part := range strings.Fields(commandPath) {
+		switch part {
+		case "help", "completion", "version":
+			return true
+		}
+	}
+	return false
+}

cmd/mapt/cmd/root_telemetry_test.go

@@ -0,0 +1,40 @@
+package cmd
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestTelemetryCounted(t *testing.T) {
+	root := &cobra.Command{Use: "mapt"}
+	aws := &cobra.Command{Use: "aws", RunE: noopRunE}
+	hosts := &cobra.Command{Use: "hosts"}
+	create := &cobra.Command{Use: "create", RunE: noopRunE}
+	list := &cobra.Command{Use: "list"}
+
+	root.AddCommand(aws)
+	aws.AddCommand(hosts)
+	hosts.AddCommand(create, list)
+
+	tests := []struct {
+		name string
+		cmd  *cobra.Command
+		want bool
+	}{
+		{"root shows help", root, false},
+		{"group with RunE", aws, false},
+		{"intermediate group", hosts, false},
+		{"leaf with RunE", create, true},
+		{"leaf without RunE shows help", list, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := telemetryCounted(tt.cmd); got != tt.want {
+				t.Fatalf("telemetryCounted(%q) = %t, want %t", tt.cmd.CommandPath(), got, tt.want)
+			}
+		})
+	}
+}
+
+func noopRunE(cmd *cobra.Command, args []string) error { return nil }

pkg/telemetry/config.go

@@ -0,0 +1,12 @@
+package telemetry
+
+// The token below is PostHog's project capture token (phc_). It is
+// intentionally committed in plain text: it is write-only, can only send
+// events into this project, and PostHog documents it as safe to expose in
+// client-side code. It must never be replaced with a personal API key
+// (phx_), which can read and modify project data.
+const (
+	posthogHost  = "https://eu.i.posthog.com"
+	posthogToken = "phc_BX33W4L8vxDghW9RYfoTn7mTauApz53sDnERYZpUCMQf"
+	capturePath  = "/i/v0/e/"
+)

pkg/telemetry/emitter.go

@@ -0,0 +1,107 @@
+package telemetry
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"runtime"
+	"runtime/debug"
+	"time"
+
+	"github.com/redhat-developer/mapt/pkg/util/logging"
+)
+
+const sendTimeout = 2 * time.Second
+
+type Event struct {
+	InstallID string
+	Version   string
+	Command   string
+}
+
+type posthogEvent struct {
+	APIKey     string         `json:"api_key"`
+	Event      string         `json:"event"`
+	DistinctID string         `json:"distinct_id"`
+	Properties map[string]any `json:"properties"`
+	Timestamp  string         `json:"timestamp"`
+}
+
+func (c *Client) Emit(event Event) <-chan struct{} {
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		c.send(event)
+	}()
+	return done
+}
+
+func (c *Client) Wait(done <-chan struct{}, timeout time.Duration) {
+	if done == nil {
+		return
+	}
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+	select {
+	case <-done:
+	case <-timer.C:
+	}
+}
+
+// version is injected at build time by the Makefile via
+// -ldflags "-X .../pkg/telemetry.version=<VERSION>", mirroring the version
+// variables of the other integrations. When unset (plain `go build`), Version
+// falls back to the module version from build info.
+var version = ""
+
+func Version() string {
+	if version != "" {
+		return version
+	}
+	info, ok := debug.ReadBuildInfo()
+	if !ok || info.Main.Version == "" || info.Main.Version == "(devel)" {
+		return "dev"
+	}
+	return info.Main.Version
+}
+
+func (c *Client) send(event Event) {
+	payload := posthogEvent{
+		APIKey:     c.apiKey,
+		Event:      "mapt.execution",
+		DistinctID: event.InstallID,
+		Properties: map[string]any{
+			"mapt_version": event.Version,
+			"command":      event.Command,
+			"os":           runtime.GOOS,
+			"arch":         runtime.GOARCH,
+			// PostHog reads the client IP from every capture request and uses
+			// it for GeoIP enrichment by default; disable it so no location
+			// data is derived from users' network addresses.
+			"$geoip_disable": true,
+		},
+		Timestamp: time.Now().UTC().Format(time.RFC3339),
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		logging.Debugf("telemetry delivery failed: %v", err)
+		return
+	}
+	request, err := http.NewRequest(http.MethodPost, c.endpoint, bytes.NewReader(data))
+	if err != nil {
+		logging.Debugf("telemetry delivery failed: %v", err)
+		return
+	}
+	request.Header.Set("Content-Type", "application/json")
+	response, err := c.httpClient.Do(request)
+	if err != nil {
+		logging.Debugf("telemetry delivery failed: %v", err)
+		return
+	}
+	defer func() { _ = response.Body.Close() }()
+	if response.StatusCode < http.StatusOK || response.StatusCode >= http.StatusMultipleChoices {
+		logging.Debugf("telemetry delivery failed: HTTP status %s", fmt.Sprint(response.Status))
+	}
+}
+