fix: gracefully handle process metrics registration failure on unsupported OSes

.chloggen/fix-aix-crash.yaml

@@ -0,0 +1,4 @@
+change_type: bug_fix
+component: pkg/service
+note: "Don't error on startup when process metrics are enabled on unsupported OSes (e.g. AIX)"
+issues: [14307]

service/service.go

@@ -223,9 +223,11 @@ func New(ctx context.Context, set Settings, cfg Config) (_ *Service, resultErr e
 		return nil, err
 	}
 
-	if err := proctelemetry.RegisterProcessMetrics(srv.telemetrySettings); err != nil {
-		return nil, fmt.Errorf("failed to register process metrics: %w", err)
+	// Register process metrics on supported OSes.
+	if err := registerProcessMetrics(srv, runtime.GOOS, proctelemetry.RegisterProcessMetrics); err != nil {
+		return nil, err
 	}
+
 	return srv, nil
 }
 
@@ -364,3 +366,30 @@ func Validate(ctx context.Context, set Settings, cfg Config) error {
 	}
 	return nil
 }
+
+// registerProcessMetrics registers process metrics on supported operating systems.
+//
+// Historically, attempting to register process metrics on unsupported platforms
+// (e.g. AIX) caused the Collector to fail at startup.
+// See https://github.com/open-telemetry/opentelemetry-collector/issues/12098
+func registerProcessMetrics(
+	srv *Service,
+	goos string,
+	register func(component.TelemetrySettings, ...proctelemetry.RegisterOption) error,
+) error {
+	switch goos {
+	// Only support the OSes that we explicitly test and build for,
+	// plus others that are known to have some support in gopsutil.
+	case "linux", "darwin", "windows", "freebsd", "openbsd", "solaris", "plan9":
+		if err := register(srv.telemetrySettings); err != nil {
+			return fmt.Errorf("failed to register process metrics: %w", err)
+		}
+	default:
+		// On unsupported OSes, log a warning and continue startup.
+		srv.telemetrySettings.Logger.Warn(
+			"Process metrics are disabled on this operating system",
+			zap.String("os", goos),
+		)
+	}
+	return nil
+}

service/service_test.go

@@ -35,6 +35,7 @@ import (
 	"go.opentelemetry.io/collector/pipeline/xpipeline"
 	"go.opentelemetry.io/collector/service/extensions"
 	"go.opentelemetry.io/collector/service/internal/builders"
+	"go.opentelemetry.io/collector/service/internal/proctelemetry"
 	"go.opentelemetry.io/collector/service/pipelines"
 	"go.opentelemetry.io/collector/service/telemetry"
 	"go.opentelemetry.io/collector/service/telemetry/otelconftelemetry"
@@ -825,3 +826,59 @@ func TestValidateGraph(t *testing.T) {
 		})
 	}
 }
+
+func TestRegisterProcessMetrics_UnsupportedOS_Warns(t *testing.T) {
+	mockRegister := func(_ component.TelemetrySettings, _ ...proctelemetry.RegisterOption) error {
+		t.Fatalf("should not be called on unsupported OS")
+		return nil
+	}
+
+	core, logs := observer.New(zapcore.WarnLevel)
+	logger := zap.New(core)
+
+	srv := &Service{
+		telemetrySettings: component.TelemetrySettings{Logger: logger},
+	}
+
+	err := registerProcessMetrics(srv, "aix", mockRegister)
+
+	require.NoError(t, err)
+	require.Equal(t, 1, logs.Len(), "Expected exactly one warning log")
+	entry := logs.All()[0]
+	require.Equal(t, "Process metrics are disabled on this operating system", entry.Message)
+	require.Equal(t, "aix", entry.ContextMap()["os"], "Log should contain the OS field")
+}
+
+func TestRegisterProcessMetrics_SupportedOS_CallsRegister(t *testing.T) {
+	called := false
+	mockRegister := func(_ component.TelemetrySettings, _ ...proctelemetry.RegisterOption) error {
+		called = true
+		return nil
+	}
+
+	srv := &Service{
+		telemetrySettings: component.TelemetrySettings{Logger: zap.NewNop()},
+	}
+
+	err := registerProcessMetrics(srv, "linux", mockRegister)
+
+	require.NoError(t, err)
+	require.True(t, called, "Registration function should be called on supported OS")
+}
+
+func TestRegisterProcessMetrics_SupportedOS_RegisterFails_ReturnsError(t *testing.T) {
+	wantErr := errors.New("boom")
+	mockRegister := func(_ component.TelemetrySettings, _ ...proctelemetry.RegisterOption) error {
+		return wantErr
+	}
+
+	srv := &Service{
+		telemetrySettings: component.TelemetrySettings{Logger: zap.NewNop()},
+	}
+
+	err := registerProcessMetrics(srv, "linux", mockRegister)
+
+	require.Error(t, err)
+	require.ErrorIs(t, err, wantErr)
+	require.Contains(t, err.Error(), "failed to register process metrics")
+}