config: add platform-agnostic 'target' property

Today the receiver config requires platform-specific fields to specify
the listen path: 'pipe' on Windows (a named pipe path) and 'socket'
on Unix (a Unix domain socket path). This means configs that use
environment variable substitution via the ${env:VAR} syntax cannot
use a single property that works across both platforms, since the
field name itself is platform-specific.

Add a new 'target' field that acts as a platform-agnostic alternative.
During Validate(), when 'target' is set, its value is copied into the
appropriate platform-specific field: NamedPipePath on Windows and
UnixSocketPath on Unix. The existing normalization logic then handles
the value as usual, including named pipe prefix expansion on Windows
and af_unix: prefix stripping on Unix.

Example usage:

```yaml
receivers:
  trace2receiver:
    target: ${env:TRACE2_TARGET}
```

Unix:
```
TRACE2_TARGET=af_unix:/var/trace2.socket ./otel --config config.yaml
```

Windows:
```
SET TRACE2_TARGET //./pipe/trace2
otel --config config.yaml
```

It is an error to specify both 'target' and the platform-specific
field ('pipe' or 'socket'), since the intent would be ambiguous.

Add tests covering the target-to-socket mapping on Unix (with and
without af_unix: prefix), the target-to-pipe mapping on Windows,
and the conflict error for both platforms.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Matthew John Cheetham <mjcheetham@outlook.com>

Author: mjcheetham

Docs/Examples/DebugDump/config.yml

@@ -16,8 +16,7 @@
 
 receivers:
   trace2receiver:
-    socket: "/usr/local/<my-install-dir>/trace2.socket"
-    pipe:   "//./pipe/<my-pipe-name>"
+    target: ${env:TRACE2_TARGET}
 
 #   filter: "/usr/local/<my-install-dir>/filter.yml"
 #   pii:    "/usr/local/<my-install-dir>/pii.yml"

Docs/Examples/ExportToAzureMonitor/config.yml

@@ -15,8 +15,7 @@
 
 receivers:
   trace2receiver:
-    socket: "/usr/local/<my-install-dir>/trace2.socket"
-    pipe:   "//./pipe/<my-pipe-name>"
+    target: ${env:TRACE2_TARGET}
 
 #   filter: "/usr/local/<my-install-dir>/filter.yml"
 #   pii:    "/usr/local/<my-install-dir>/pii.yml"

Docs/configure-custom-collector.md

@@ -42,8 +42,7 @@ The `trace2receiver` component has the following config values:
 ```
 receivers:
   trace2receiver:
-    socket: <unix-domain-socket-pathname>
-    pipe:   <windows-named-pipe-pathname>
+    target: <trace2-target>
     pii:    <pii-settings-pathname>
     filter: <filter-settings-pathname>
 ```
@@ -53,17 +52,26 @@ For example:
 ```
 receivers:
   trace2receiver:
-    socket: "/usr/local/my-collector/trace2.socket"
-    pipe:   "//./pipe/my-collector.pipe"
+    target: "/usr/local/my-collector/trace2.socket"
     pii:    "/usr/local/my-collector/pii.yml"
     filter: "/usr/local/my-collector/filter.yml"
 ```
 
-### `<unix-domain-socket-pathname>` (Required on Unix)
+### `<trace2-target>` (Required)
 
-The pathname will be used on Linux and macOS hosts to create a Unix
-Domain Socket where the receiver will listen for telemetry from Git
-commands.  The socket will be created when the collector starts up.
+The `target` property is a string that specifies where the `trace2receiver`
+should listen for Trace2 telemetry from Git commands. This is required.
+It must be a pathname to a Unix Domain Socket on Unix hosts, or a pathname to a
+Windows Named Pipe on Windows hosts. The collector will create the socket or
+named pipe when it starts up. The `target` property can be specified directly
+as a string literal, or it can be specified indirectly using an environment
+variable. For example:
+
+```
+receivers:
+  trace2receiver:
+    target: ${env:TRACE2_TARGET}
+```
 
 To tell Git to send Trace2 telemetry to the receiver, you must set
 the Git `trace2.eventtarget` config setting at the `global` or
@@ -74,14 +82,34 @@ and
 [enabling a target](https://git-scm.com/docs/api-trace2#_enabling_a_target)
 for details.
 
+#### Unix
 ```
 $ git config --system trace2.eventtarget "af_unix:/usr/local/my-collector/trace2.socket"
 ```
 
 _The `af_unix:` prefix is required to tell Git that it should expect a
 Unix Domain Socket rather than a plain file._
 
-### `<windows-named-pipe-pathname>` (Required on Windows)
+#### Windows
+```
+$ git config --system trace2.eventtarget "//./pipe/my-collector.pipe"
+```
+
+_The `//./pipe/` prefix is required to tell Git that it should expect a
+Windows Named Pipe rather than a plain file._
+
+### `<unix-domain-socket-pathname>` (Unix-only, deprecated)
+
+The pathname will be used on Linux and macOS hosts to create a Unix
+Domain Socket where the receiver will listen for telemetry from Git
+commands.  The socket will be created when the collector starts up.
+
+Replaced by the more general `<trace2-target>` config value, which can be used
+on all platforms. It is an error to set both `target` and
+`unix-domain-socket-pathname`. If both are set, then then collector will fail to
+start.
+
+### `<windows-named-pipe-pathname>` (Windows-only, deprecated)
 
 The pathname will be used on Windows hosts to create a Windows Named
 Pipe where the receiver will listen for telemetry from Git commands.
@@ -90,18 +118,10 @@ pathname must refer to a local named pipe `//./pipe/...` because named
 pipe servers can only create and listen on local pipes.  You may use
 forward or backslashes.
 
-To tell Git to send Trace2 telemetry to the receiver, you must set
-the Git `trace2.eventtarget` config setting at the `global` or
-`system` level to this named pipe pathname.  See the Git Trace2 API
-documentation on the
-[event format target](https://git-scm.com/docs/api-trace2#_the_event_format_target)
-and
-[enabling a target](https://git-scm.com/docs/api-trace2#_enabling_a_target)
-for details.
-
-```
-$ git config --system trace2.eventtarget "//./pipe/my-collector.pipe"
-```
+Replaced by the more general `<trace2-target>` config value, which can be used
+on all platforms. It is an error to set both `target` and
+`windows-named-pipe-pathname`. If both are set, then then collector will fail to
+start.
 
 ### `<pii-settings-pathname>` (Optional)
 

config.go

@@ -41,6 +41,18 @@ type Config struct {
 	// This config file field is ignored on Windows platforms.
 	UnixSocketPath string `mapstructure:"socket"`
 
+	// A combination of either a NamedPipePath or a UnixSocketPath.
+	// On Unix this can only be considered as a Unix domain socket,
+	// and on Windows we can only consider it as a named pipe.
+	// This allows the user to specify a property that works for
+	// either platform, and we will normalize it to the correct one
+	// at runtime. If both are specified we consider this an error.
+	// The idea behind this is to allow users to specify the value
+	// of the Target property as an environment variable via the
+	// ${env:VAR} syntax, and then use that environment variable to
+	// set the correct path for their platform.
+	Target string `mapstructure:"target"`
+
 	// Allow command and control verbs to be embedded in the Trace2
 	// data stream.
 	AllowCommandControlVerbs bool `mapstructure:"enable_commands"`
@@ -79,6 +91,23 @@ func (cfg *Config) Validate() error {
 	var path string
 	var err error
 
+	// If `target` is set, normalize it into the platform-specific
+	// field.  It is an error to set both `target` and the
+	// platform-specific field.
+	if len(cfg.Target) > 0 {
+		if runtime.GOOS == "windows" {
+			if len(cfg.NamedPipePath) > 0 {
+				return fmt.Errorf("receivers.trace2receiver: cannot specify both 'target' and 'pipe'")
+			}
+			cfg.NamedPipePath = cfg.Target
+		} else {
+			if len(cfg.UnixSocketPath) > 0 {
+				return fmt.Errorf("receivers.trace2receiver: cannot specify both 'target' and 'socket'")
+			}
+			cfg.UnixSocketPath = cfg.Target
+		}
+	}
+
 	if runtime.GOOS == "windows" {
 		if len(cfg.NamedPipePath) == 0 {
 			return fmt.Errorf("receivers.trace2receiver.pipe not defined")

config_test.go

@@ -356,6 +356,83 @@ func Test_Config_Validate_WithCommandControlEnabled(t *testing.T) {
 	assert.NoError(t, err)
 }
 
+// Test Validate with Target on Unix sets UnixSocketPath
+func Test_Config_Validate_TargetUnix(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Skipping Unix-specific test")
+	}
+
+	cfg := &Config{
+		Target: "/tmp/test.socket",
+	}
+
+	err := cfg.Validate()
+	assert.NoError(t, err)
+	assert.Equal(t, "/tmp/test.socket", cfg.UnixSocketPath)
+}
+
+// Test Validate with Target with af_unix prefix on Unix
+func Test_Config_Validate_TargetAfUnixPrefixUnix(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Skipping Unix-specific test")
+	}
+
+	cfg := &Config{
+		Target: "af_unix:/tmp/test.socket",
+	}
+
+	err := cfg.Validate()
+	assert.NoError(t, err)
+	assert.Equal(t, "/tmp/test.socket", cfg.UnixSocketPath)
+}
+
+// Test Validate with Target on Windows sets NamedPipePath
+func Test_Config_Validate_TargetWindows(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		t.Skip("Skipping Windows-specific test")
+	}
+
+	cfg := &Config{
+		Target: "test-pipe",
+	}
+
+	err := cfg.Validate()
+	assert.NoError(t, err)
+	assert.Equal(t, `\\.\pipe\test-pipe`, cfg.NamedPipePath)
+}
+
+// Test Validate rejects Target and socket both set on Unix
+func Test_Config_Validate_TargetAndSocketConflictUnix(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Skipping Unix-specific test")
+	}
+
+	cfg := &Config{
+		Target:         "/tmp/target.socket",
+		UnixSocketPath: "/tmp/test.socket",
+	}
+
+	err := cfg.Validate()
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "cannot specify both 'target' and 'socket'")
+}
+
+// Test Validate rejects Target and pipe both set on Windows
+func Test_Config_Validate_TargetAndPipeConflictWindows(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		t.Skip("Skipping Windows-specific test")
+	}
+
+	cfg := &Config{
+		Target:        "target-pipe",
+		NamedPipePath: "test-pipe",
+	}
+
+	err := cfg.Validate()
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "cannot specify both 'target' and 'pipe'")
+}
+
 // Helper function to create a minimal valid config for the current platform
 func createMinimalValidConfig() *Config {
 	if runtime.GOOS == "windows" {