Add telemetry notice to azd (#2581)

* Add telemetry notice to azd

* Add runcontext to cspell config

* lll

* Add tests for runcontext's Cloud Shell

* Review feedback

* More review feedback

Author: danieljurek

cli/azd/.vscode/cspell.yaml

@@ -17,6 +17,7 @@ words:
   - devcontainers
   - goversioninfo
   - nosec
+  - runcontext
 languageSettings:
   - languageId: go
     ignoreRegExpList:

cli/azd/internal/runcontext/cloudshell.go

@@ -0,0 +1,20 @@
+package runcontext
+
+import (
+	"log"
+	"os"
+	"strconv"
+)
+
+const cUseCloudShellAuthEnvVar = "AZD_IN_CLOUDSHELL"
+
+func IsRunningInCloudShell() bool {
+	if azdInCloudShell, has := os.LookupEnv(cUseCloudShellAuthEnvVar); has {
+		if use, err := strconv.ParseBool(azdInCloudShell); err == nil && use {
+			log.Printf("running in Cloud Shell")
+			return true
+		}
+	}
+
+	return false
+}

cli/azd/internal/runcontext/cloudshell_test.go

@@ -0,0 +1,32 @@
+package runcontext
+
+import (
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+const cAzdInCloudShellEnvVar = "AZD_IN_CLOUDSHELL"
+
+func TestIsRunningInCloudShellScenarios(t *testing.T) {
+	t.Run("returns true when AZD_IN_CLOUDSHELL is set to true-ish string", func(t *testing.T) {
+		t.Setenv(cAzdInCloudShellEnvVar, "1")
+		require.True(t, IsRunningInCloudShell())
+	})
+
+	t.Run("returns false when AZD_IN_CLOUDSHELL is set to false-ish string", func(t *testing.T) {
+		t.Setenv(cAzdInCloudShellEnvVar, "0")
+		require.False(t, IsRunningInCloudShell())
+	})
+
+	t.Run("returns false when AZD_IN_CLOUDSHELL is not set", func(t *testing.T) {
+		// Ensure that AZD_IN_CLOUDSHELL is not set otherwise the test is not
+		// accurate
+		_, envIsSet := os.LookupEnv(cAzdInCloudShellEnvVar)
+		require.False(t, envIsSet)
+
+		require.False(t, IsRunningInCloudShell())
+	})
+
+}

cli/azd/internal/telemetry/notice.go

@@ -0,0 +1,91 @@
+package telemetry
+
+import (
+	"errors"
+	"io/fs"
+	"log"
+	"os"
+	"path/filepath"
+
+	"github.com/azure/azure-dev/cli/azd/internal/runcontext"
+	"github.com/azure/azure-dev/cli/azd/pkg/config"
+)
+
+// Telemetry notice text displayed to the user in some scenarios
+//
+//nolint:lll
+const cTelemetryNoticeText = `The Azure Developer CLI collects usage data and sends that usage data to Microsoft in order to help us improve your experience.
+You can opt-out of telemetry by setting the AZURE_DEV_COLLECT_TELEMETRY environment variable to 'no' in the shell you use.
+
+Read more about Azure Developer CLI telemetry: https://github.com/Azure/azure-dev#data-collection`
+
+// The name of the file created in the azd configuration directory after the
+// first run of the CLI. It's presence is used to determine if this is the
+// first run of the CLI.
+const cFirstRunFileName = "first-run"
+
+func FirstNotice() string {
+	// If the AZURE_DEV_COLLECT_TELEMETRY environment variable is set to any
+	// value, don't display the telemetry notice. The user has either opted into
+	// or out of telemetry already.
+	if _, has := os.LookupEnv(collectTelemetryEnvVar); has {
+		return ""
+	}
+
+	// First run is only displayed when running in Cloud Shell
+	if runcontext.IsRunningInCloudShell() && !noticeShown() {
+		err := SetupFirstRun()
+		if err != nil {
+			log.Printf("failed to setup first run: %v", err)
+		}
+
+		return cTelemetryNoticeText
+	}
+
+	return ""
+}
+
+func noticeShown() bool {
+	firstRunFilePath, err := getFirstRunFilePath()
+	if err != nil {
+		log.Printf("failed to get first run file path: %v", err)
+		// Assume no notice has been show
+		return false
+	}
+
+	if _, err := os.Stat(firstRunFilePath); err == nil {
+		// First run file exists, this is not the first run
+		return true
+	} else if errors.Is(err, fs.ErrNotExist) {
+		// The file does not exist, this is the first run
+		return false
+	} else {
+		log.Printf("failed to stat first run file: %v", err)
+		// If the first run file can't be read assume notice hasn't been shown
+		return false
+	}
+}
+
+func getFirstRunFilePath() (string, error) {
+	configDir, err := config.GetUserConfigDir()
+	if err != nil {
+		log.Printf("failed to get user config dir: %v", err)
+		return "", err
+	}
+
+	return filepath.Join(configDir, cFirstRunFileName), nil
+}
+
+func SetupFirstRun() error {
+	firstRunFilePath, err := getFirstRunFilePath()
+	if err != nil {
+		return err
+	}
+
+	_, err = os.Create(firstRunFilePath)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}

cli/azd/internal/telemetry/notice_test.go

@@ -0,0 +1,120 @@
+package telemetry
+
+import (
+	"os"
+	"testing"
+
+	"github.com/azure/azure-dev/cli/azd/test/ostest"
+	"github.com/stretchr/testify/assert"
+)
+
+func setupSuite(withFirstRunFile bool, t *testing.T) func(t *testing.T) {
+	firstRunFilePath, err := getFirstRunFilePath()
+	if err != nil {
+		t.Fatalf("failed to get first run file path: %v", err)
+	}
+
+	var tmpFilename string
+	// If the first-run file exists
+	if noticeShown() {
+
+		// Move the first-run file out of the way but keep its local contents
+		// (if any), content can be restored on teardown.
+		if !withFirstRunFile {
+			file, err := os.CreateTemp("", "azd-test-")
+			if err != nil {
+				t.Fatalf("failed to create temp file: %v", err)
+			}
+			file.Close()
+
+			tmpFilename = file.Name()
+			err = os.Rename(firstRunFilePath, tmpFilename)
+			if err != nil {
+				t.Fatalf("failed to rename first run file: %v", err)
+			}
+
+			return func(t *testing.T) {
+				err = os.Rename(tmpFilename, firstRunFilePath)
+				if err != nil {
+					t.Fatalf("failed to rename first run file: %v", err)
+				}
+			}
+		}
+	} else {
+		if withFirstRunFile {
+			// Create a first-run file to simulate the existence of a first-run
+			// file, remove the created file on teardown.
+			file, err := os.Create(firstRunFilePath)
+			if err != nil {
+				t.Fatalf("failed to create first run file: %v", err)
+			}
+			file.Close()
+
+			return func(t *testing.T) {
+				err = os.Remove(firstRunFilePath)
+				if err != nil {
+					t.Fatalf("failed to remove first run file: %v", err)
+				}
+			}
+		}
+	}
+
+	// No setup or teardown required
+	return func(t *testing.T) {}
+}
+
+func Test_FirstNotice(t *testing.T) {
+	t.Run("in Cloud Shell", func(t *testing.T) {
+		ostest.Setenv(t, "AZD_IN_CLOUDSHELL", "1")
+
+		t.Run("returns nothing if opted into telemetry", func(t *testing.T) {
+			teardown := setupSuite(false, t)
+			defer teardown(t)
+
+			ostest.Setenv(t, collectTelemetryEnvVar, "yes")
+			assert.Empty(t, FirstNotice(), "should not display telemetry notice if opted in")
+		})
+
+		t.Run("returns nothing if opted out of telemetry", func(t *testing.T) {
+			teardown := setupSuite(false, t)
+			defer teardown(t)
+
+			ostest.Setenv(t, collectTelemetryEnvVar, "no")
+			assert.Empty(t, FirstNotice(), "should not display telemetry notice if opted out")
+		})
+
+		t.Run("returns nothing if first run file exists", func(t *testing.T) {
+			teardown := setupSuite(true, t)
+			defer teardown(t)
+
+			assert.Empty(t, FirstNotice(), "should not display telemetry notice if first run file exists")
+		})
+	})
+
+	t.Run("not in Cloud Shell", func(t *testing.T) {
+		ostest.Unsetenv(t, "AZD_IN_CLOUDSHELL")
+
+		t.Run("returns nothing if first run file doesn't exist", func(t *testing.T) {
+			teardown := setupSuite(false, t)
+			defer teardown(t)
+
+			assert.Empty(t, FirstNotice(), "should not display telemetry notice if first run file doesn't exist")
+		})
+
+		t.Run("returns nothing if opted into telemetry", func(t *testing.T) {
+			teardown := setupSuite(false, t)
+			defer teardown(t)
+
+			ostest.Setenv(t, collectTelemetryEnvVar, "yes")
+			assert.Empty(t, FirstNotice(), "should not display telemetry notice if opted in")
+		})
+
+		t.Run("returns nothing if opted out of telemetry", func(t *testing.T) {
+			teardown := setupSuite(false, t)
+			defer teardown(t)
+
+			ostest.Setenv(t, collectTelemetryEnvVar, "no")
+			assert.Empty(t, FirstNotice(), "should not display telemetry notice if opted out")
+		})
+	})
+}

cli/azd/internal/telemetry/telemetry.go

@@ -15,6 +15,7 @@ import (
 	"time"
 
 	"github.com/azure/azure-dev/cli/azd/internal"
+	"github.com/azure/azure-dev/cli/azd/internal/runcontext"
 	appinsightsexporter "github.com/azure/azure-dev/cli/azd/internal/telemetry/appinsights-exporter"
 	"github.com/azure/azure-dev/cli/azd/internal/tracing/resource"
 	"github.com/azure/azure-dev/cli/azd/pkg/config"
@@ -65,7 +66,17 @@ func getTelemetryDirectory() (string, error) {
 }
 
 func IsTelemetryEnabled() bool {
-	return os.Getenv(collectTelemetryEnvVar) != "no"
+	// If the user has opted out of telemetry directly, don't collect telemetry.
+	if os.Getenv(collectTelemetryEnvVar) == "no" {
+		return false
+	}
+
+	// If it's the first run and we're in cloud shell, don't collect telemetry.
+	if noticeShown() && runcontext.IsRunningInCloudShell() {
+		return false
+	}
+
+	return true
 }
 
 // Returns the singleton TelemetrySystem instance.

cli/azd/main.go

@@ -58,6 +58,13 @@ func main() {
 	go fetchLatestVersion(latest)
 
 	cmdErr := cmd.NewRootCmd(false, nil).ExecuteContext(ctx)
+
+	if !isJsonOutput() {
+		if firstNotice := telemetry.FirstNotice(); firstNotice != "" {
+			fmt.Fprintln(os.Stderr, output.WithWarningFormat(firstNotice))
+		}
+	}
+
 	latestVersion, ok := <-latest
 
 	// If we were able to fetch a latest version, check to see if we are up to date and