Add --telemetry CLI parameter for custom user agent telemetry

cmd/credentialUtil.go

@@ -366,7 +366,7 @@ func isPublic(ctx context.Context, blobResourceURL string, cpkOptions common.Cpk
 		RetryDelay:    ste.UploadRetryDelay,
 		MaxRetryDelay: ste.UploadMaxRetryDelay,
 	}, policy.TelemetryOptions{
-		ApplicationID: common.AddUserAgentPrefix(common.UserAgent),
+		ApplicationID: buildUserAgentWithTelemetry(common.UserAgent),
 	}, nil, ste.LogOptions{}, nil, nil)
 
 	blobClient, _ := blob.NewClientWithNoCredential(bURLParts.String(), &blob.ClientOptions{ClientOptions: clientOptions})
@@ -399,7 +399,7 @@ func mdAccountNeedsOAuth(ctx context.Context, blobResourceURL string, cpkOptions
 		RetryDelay:    ste.UploadRetryDelay,
 		MaxRetryDelay: ste.UploadMaxRetryDelay,
 	}, policy.TelemetryOptions{
-		ApplicationID: common.AddUserAgentPrefix(common.UserAgent),
+		ApplicationID: buildUserAgentWithTelemetry(common.UserAgent),
 	}, nil, ste.LogOptions{}, nil, nil)
 
 	blobClient, _ := blob.NewClientWithNoCredential(blobResourceURL, &blob.ClientOptions{ClientOptions: clientOptions})
@@ -593,8 +593,24 @@ func createClientOptions(logger common.ILoggerResetable, srcCred *common.ScopedT
 		RetryDelay:    ste.UploadRetryDelay,
 		MaxRetryDelay: ste.UploadMaxRetryDelay,
 	}, policy.TelemetryOptions{
-		ApplicationID: common.AddUserAgentPrefix(common.UserAgent),
+		ApplicationID: buildUserAgentWithTelemetry(common.UserAgent),
 	}, ste.NewAzcopyHTTPClient(frontEndMaxIdleConnectionsPerHost), logOptions, srcCred, reauthCred)
 }
 
 const frontEndMaxIdleConnectionsPerHost = http.DefaultMaxIdleConnsPerHost
+
+// buildUserAgentWithTelemetry creates the user agent string including both
+// environment variable prefix and CLI telemetry parameter
+func buildUserAgentWithTelemetry(baseUserAgent string) string {
+	userAgent := baseUserAgent
+
+	// Add CLI telemetry parameter if provided
+	if len(azcopyTelemetryValue) > 0 {
+		userAgent = azcopyTelemetryValue + " " + userAgent
+	}
+
+	// Add environment variable prefix if set
+	userAgent = common.AddUserAgentPrefix(userAgent)
+
+	return userAgent
+}

cmd/root.go

@@ -62,6 +62,7 @@ var azcopySkipVersionCheck bool
 var isPipeDownload bool
 var retryStatusCodes string
 var debugMemoryProfile string
+var azcopyTelemetryValue string
 
 type jobLoggerInfo struct {
 	jobID         common.JobID
@@ -287,6 +288,8 @@ func init() {
 
 	rootCmd.PersistentFlags().BoolVar(&azcopySkipVersionCheck, "skip-version-check", false, "Do not perform the version check at startup. Intended for automation scenarios & airgapped use.")
 
+	rootCmd.PersistentFlags().StringVar(&azcopyTelemetryValue, "telemetry", "", "Adds additional telemetry information to the AzCopy user agent for identifying customers or partners in backend systems. This value is prefixed to the user agent string.")
+
 	// Note: this is due to Windows not supporting signals properly
 	rootCmd.PersistentFlags().BoolVar(&cancelFromStdin, "cancel-from-stdin", false, "Used by partner teams to send in `cancel` through stdin to stop a job.")
 

cmd/telemetry_integration_test.go

@@ -0,0 +1,58 @@
+package cmd
+
+import (
+	"testing"
+	"os"
+)
+
+func TestTelemetryIntegration(t *testing.T) {
+	// Save original values to restore later
+	originalTelemetry := azcopyTelemetryValue
+	originalEnv := os.Getenv("AZCOPY_USER_AGENT_PREFIX")
+	defer func() {
+		azcopyTelemetryValue = originalTelemetry
+		if originalEnv != "" {
+			os.Setenv("AZCOPY_USER_AGENT_PREFIX", originalEnv)
+		} else {
+			os.Unsetenv("AZCOPY_USER_AGENT_PREFIX")
+		}
+	}()
+
+	baseUserAgent := "AzCopy/10.29.1" // Use static version for predictable testing
+
+	// Test case 1: Only CLI telemetry parameter
+	azcopyTelemetryValue = "MyCompany/1.0"
+	os.Unsetenv("AZCOPY_USER_AGENT_PREFIX")
+	result := buildUserAgentWithTelemetry(baseUserAgent)
+	expected := "MyCompany/1.0 AzCopy/10.29.1"
+	if result != expected {
+		t.Errorf("CLI telemetry only: expected %s, got %s", expected, result)
+	}
+
+	// Test case 2: Only environment variable
+	azcopyTelemetryValue = ""
+	os.Setenv("AZCOPY_USER_AGENT_PREFIX", "EnvPrefix/1.0")
+	result = buildUserAgentWithTelemetry(baseUserAgent)
+	expected = "EnvPrefix/1.0 AzCopy/10.29.1"
+	if result != expected {
+		t.Errorf("Env prefix only: expected %s, got %s", expected, result)
+	}
+
+	// Test case 3: Both CLI telemetry and environment variable
+	azcopyTelemetryValue = "MyCompany/1.0"
+	os.Setenv("AZCOPY_USER_AGENT_PREFIX", "EnvPrefix/1.0")
+	result = buildUserAgentWithTelemetry(baseUserAgent)
+	expected = "EnvPrefix/1.0 MyCompany/1.0 AzCopy/10.29.1"
+	if result != expected {
+		t.Errorf("Both CLI and env: expected %s, got %s", expected, result)
+	}
+
+	// Test case 4: Neither CLI nor environment variable
+	azcopyTelemetryValue = ""
+	os.Unsetenv("AZCOPY_USER_AGENT_PREFIX")
+	result = buildUserAgentWithTelemetry(baseUserAgent)
+	expected = "AzCopy/10.29.1"
+	if result != expected {
+		t.Errorf("Neither CLI nor env: expected %s, got %s", expected, result)
+	}
+}

cmd/telemetry_test.go

@@ -0,0 +1,40 @@
+package cmd
+
+import (
+	"testing"
+	"github.com/Azure/azure-storage-azcopy/v10/common"
+)
+
+func TestBuildUserAgentWithTelemetry(t *testing.T) {
+	// Save original value to restore later
+	originalTelemetry := azcopyTelemetryValue
+	defer func() {
+		azcopyTelemetryValue = originalTelemetry
+	}()
+
+	baseUserAgent := common.UserAgent
+
+	// Test 1: No telemetry value
+	azcopyTelemetryValue = ""
+	result := buildUserAgentWithTelemetry(baseUserAgent)
+	// Should have only the base user agent (possibly with env prefix)
+	if result != common.AddUserAgentPrefix(baseUserAgent) {
+		t.Errorf("Expected %s, got %s", common.AddUserAgentPrefix(baseUserAgent), result)
+	}
+
+	// Test 2: With telemetry value
+	azcopyTelemetryValue = "MyCompany/1.0"
+	result = buildUserAgentWithTelemetry(baseUserAgent)
+	// Should have telemetry prefix followed by user agent
+	expected := common.AddUserAgentPrefix("MyCompany/1.0 " + baseUserAgent)
+	if result != expected {
+		t.Errorf("Expected %s, got %s", expected, result)
+	}
+
+	// Test 3: Empty telemetry value should be handled gracefully
+	azcopyTelemetryValue = ""
+	result = buildUserAgentWithTelemetry(baseUserAgent)
+	if result != common.AddUserAgentPrefix(baseUserAgent) {
+		t.Errorf("Expected %s, got %s", common.AddUserAgentPrefix(baseUserAgent), result)
+	}
+}