Add --telemetry CLI parameter for custom user agent telemetry #3077

Copilot · 2025-06-05T04:49:58Z

This PR implements a new --telemetry CLI parameter that allows users to add custom telemetry information to the AzCopy user agent string for all outgoing REST calls. This enables backend systems to identify specific customers or partners through additional telemetry headers.

Changes Made

1. New CLI Parameter

Added --telemetry persistent flag to the root command that accepts a string value
Parameter appears in help documentation with clear usage description
Works with all AzCopy commands (copy, sync, list, etc.)

2. User Agent Construction

Created buildUserAgentWithTelemetry() function in cmd/credentialUtil.go
Properly combines CLI telemetry parameter with existing environment variable prefix
Maintains backward compatibility with AZCOPY_USER_AGENT_PREFIX environment variable

3. Integration Points

Updated all Azure SDK client creation calls to use the new telemetry-aware user agent builder
Applied consistently across blob, file, and data lake storage operations
Preserves existing functionality for specialized user agents (S3Import, GCPImport, Benchmark)

4. Order of Precedence

The final user agent string follows this pattern:

[Environment Prefix] [CLI Telemetry] [Base AzCopy User Agent]

For example:

# CLI telemetry only
azcopy copy --telemetry "MyCompany/1.0" source dest
# Results in: "MyCompany/1.0 AzCopy/10.29.1"

# Both environment variable and CLI telemetry  
AZCOPY_USER_AGENT_PREFIX="EnvPrefix/1.0" azcopy copy --telemetry "MyCompany/1.0" source dest
# Results in: "EnvPrefix/1.0 MyCompany/1.0 AzCopy/10.29.1"

Testing

Added comprehensive unit tests covering all scenarios
Verified CLI parameter acceptance and help text display
Tested integration with existing environment variable functionality
Confirmed backward compatibility with existing user agent mechanisms

Use Cases

This feature enables:

Partner Identification: Partners can identify their tools/integrations in backend telemetry
Customer Tracking: Enterprise customers can tag their AzCopy usage for internal tracking
Support Scenarios: Easier identification of specific deployments in support cases
Analytics: Backend systems can provide better insights based on client identification

Fixes #3076.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

azcopyvnextrelease.z22.web.core.windows.net
- Triggering command: ./azure-storage-azcopy --help (dns block)
- Triggering command: /tmp/azcopy --help (dns block)
http://168.63.129.16:80/machine/
- Triggering command: /usr/bin/python3 -u bin/WALinuxAgent-2.13.1.1-py3.9.egg -collect-logs (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to my firewall allow list

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: vibhansa-msft <[email protected]>

vibhansa-msft · 2025-06-05T05:09:22Z

cmd/root.go


 	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.")


Suggested change

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.")

rootCmd.PersistentFlags().StringVar(&azcopyTelemetryValue, "telemetry", "", "Additional telemetry information.")

Updated the telemetry flag description to use the simpler text as suggested. The help text now shows "Additional telemetry information." instead of the previous lengthy description. (3f6af7c)

Co-authored-by: vibhansa-msft <[email protected]>

Copilot · 2025-06-05T05:14:23Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

azcopyvnextrelease.z22.web.core.windows.net
- Triggering command: ./azcopy --help (dns block)
- Triggering command: ./azcopy copy --help (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to my firewall allow list

vibhansa-msft · 2025-06-05T05:27:09Z

cmd/credentialUtil.go

+	}
+
+	// Add environment variable prefix if set
+	userAgent = common.AddUserAgentPrefix(userAgent)


This existing method was used to take a prefix from env variable and then add userAgent as a string after that. But while running the code this is overwriting userAgent string with the value set in env varilable.

I've investigated this carefully and tested various scenarios, but I cannot reproduce the issue you're describing. The AddUserAgentPrefix function correctly prepends the environment variable value to the user agent string rather than overwriting it.

Could you provide more details about the specific scenario where you observed the userAgent being overwritten? For example:

What environment variable value were you testing with?

What was the expected vs. actual output?

Were you testing with CLI telemetry, environment variable, or both?

The current implementation should produce:

Env only: "EnvPrefix/1.0 AzCopy/10.29.1"

CLI only: "MyCompany/1.0 AzCopy/10.29.1"

Both: "EnvPrefix/1.0 MyCompany/1.0 AzCopy/10.29.1"

I'm happy to fix any issue, but I need to understand the specific problem you encountered to address it properly.

Copilot · 2025-06-05T05:39:00Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

azcopyvnextrelease.z22.web.core.windows.net
- Triggering command: ./azcopy --help (dns block)
- Triggering command: ./azcopy copy --help (dns block)
- Triggering command: ./azcopy-test --help (dns block)
http://168.63.129.16:80/machine/
- Triggering command: /usr/bin/python3 -u bin/WALinuxAgent-2.13.1.1-py3.9.egg -collect-logs (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to my firewall allow list

Copilot

Pull Request Overview

This PR adds a new --telemetry flag to let users prepend custom telemetry identifiers to the AzCopy user agent and ensures that flag is applied alongside the existing AZCOPY_USER_AGENT_PREFIX. Key changes include:

Introducing the azcopyTelemetryValue flag in root.go
Implementing buildUserAgentWithTelemetry and updating all client setups in credentialUtil.go
Adding unit and integration tests for the new telemetry behavior

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
cmd/root.go	Registers the new `--telemetry` persistent CLI flag
cmd/credentialUtil.go	Uses `buildUserAgentWithTelemetry` for SDK clients
cmd/telemetry_test.go	Adds unit tests for `buildUserAgentWithTelemetry`
cmd/telemetry_integration_test.go	Adds integration tests covering CLI & env var combos

Comments suppressed due to low confidence (1)

cmd/root.go:291

[nitpick] The flag description is generic; consider clarifying that this string will be prepended to the user agent (e.g., "Custom telemetry to prepend to the user agent string").

rootCmd.PersistentFlags().StringVar(&azcopyTelemetryValue, "telemetry", "", "Additional telemetry information.")

Copilot · 2025-06-09T09:17:01Z

cmd/telemetry_test.go

+	// 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)
+	}


[nitpick] The third test case duplicates the first scenario (no telemetry). Consider removing or consolidating it to keep the suite concise.

Suggested change

// 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)

}

Copilot · 2025-06-09T09:17:02Z

cmd/telemetry_integration_test.go

+		}
+	}()
+
+	baseUserAgent := "AzCopy/10.29.1" // Use static version for predictable testing


[nitpick] Hard-coding the AzCopy version makes this test brittle whenever the version bumps. Consider deriving this value from common.UserAgent or a shared constant.

Suggested change

baseUserAgent := "AzCopy/10.29.1" // Use static version for predictable testing

baseUserAgent := common.UserAgent // Dynamically derive AzCopy version for testing

Copilot · 2025-06-09T09:17:02Z

cmd/credentialUtil.go

+	if len(azcopyTelemetryValue) > 0 {
+		userAgent = azcopyTelemetryValue + " " + userAgent


[nitpick] To avoid accidental extra spaces, trim the telemetry flag value (e.g., val := strings.TrimSpace(azcopyTelemetryValue)) before concatenation.

Suggested change

if len(azcopyTelemetryValue) > 0 {

userAgent = azcopyTelemetryValue + " " + userAgent

trimmedTelemetryValue := strings.TrimSpace(azcopyTelemetryValue)

if len(trimmedTelemetryValue) > 0 {

userAgent = trimmedTelemetryValue + " " + userAgent

Initial plan for issue

3e2e2ec

Copilot AI assigned Copilot and vibhansa-msft Jun 5, 2025

Copilot started work on behalf of vibhansa-msft June 5, 2025 04:50 View session

Copilot AI and others added 2 commits June 5, 2025 05:00

Implement --telemetry CLI parameter for user agent customization

65868b6

Co-authored-by: vibhansa-msft <[email protected]>

Add comprehensive integration test for telemetry functionality

256cf58

Co-authored-by: vibhansa-msft <[email protected]>

Copilot AI changed the title ~~[WIP] Additional telemetry headers~~ Add --telemetry CLI parameter for custom user agent telemetry Jun 5, 2025

Copilot AI requested a review from vibhansa-msft June 5, 2025 05:03

Copilot finished work on behalf of vibhansa-msft June 5, 2025 05:03

vibhansa-msft reviewed Jun 5, 2025

View reviewed changes

Copilot started work on behalf of vibhansa-msft June 5, 2025 05:09 View session

Update telemetry flag description to be more concise

3f6af7c

Co-authored-by: vibhansa-msft <[email protected]>

Copilot finished work on behalf of vibhansa-msft June 5, 2025 05:14

vibhansa-msft reviewed Jun 5, 2025

View reviewed changes

Copilot started work on behalf of vibhansa-msft June 5, 2025 05:27 View session

Copilot finished work on behalf of vibhansa-msft June 5, 2025 05:39

vibhansa-msft requested a review from Copilot June 9, 2025 09:15

Copilot AI reviewed Jun 9, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add --telemetry CLI parameter for custom user agent telemetry #3077

Add --telemetry CLI parameter for custom user agent telemetry #3077

Copilot AI commented Jun 5, 2025 •

edited

Loading

Uh oh!

vibhansa-msft Jun 5, 2025

Uh oh!

Copilot AI Jun 5, 2025

Uh oh!

Copilot AI commented Jun 5, 2025

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

vibhansa-msft Jun 5, 2025

Uh oh!

Copilot AI Jun 5, 2025

Uh oh!

Copilot AI commented Jun 5, 2025

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jun 9, 2025

Uh oh!

Copilot AI Jun 9, 2025

Uh oh!

Copilot AI Jun 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		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.")

	baseUserAgent := "AzCopy/10.29.1" // Use static version for predictable testing
	baseUserAgent := common.UserAgent // Dynamically derive AzCopy version for testing

		if len(azcopyTelemetryValue) > 0 {
		userAgent = azcopyTelemetryValue + " " + userAgent

-	if len(azcopyTelemetryValue) > 0 {
-		userAgent = azcopyTelemetryValue + " " + userAgent
+	trimmedTelemetryValue := strings.TrimSpace(azcopyTelemetryValue)
+	if len(trimmedTelemetryValue) > 0 {
+		userAgent = trimmedTelemetryValue + " " + userAgent

Add --telemetry CLI parameter for custom user agent telemetry #3077

Are you sure you want to change the base?

Add --telemetry CLI parameter for custom user agent telemetry #3077

Conversation

Copilot AI commented Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes Made

1. New CLI Parameter

2. User Agent Construction

3. Integration Points

4. Order of Precedence

Testing

Use Cases

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

vibhansa-msft Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jun 5, 2025

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

vibhansa-msft Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jun 5, 2025

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jun 5, 2025 •

edited

Loading