Add support for deprecated component type aliases

This change allows component authors to register one optional deprecated alias per component type, enabling smooth migrations when renaming components. When an alias is used in configuration, the collector will automatically resolve it to the original component and log a deprecation warning.

Changes:
- Add `WithDeprecatedTypeAlias` factory option to experimental modules (xreceiver, xexporter, xprocessor, xconnector)
- Add `DeprecatedAlias()` method to factory interfaces
- Generate alias expansion code in builder template that:
  - Populates factory maps with aliases pointing to original factories
  - Updates module information maps for aliased types
  - Validates that aliases don't conflict with existing component types
- Add deprecation warnings that log when an alias is used: "Using deprecated alias <alias>; use <original> instead"

Extensions are left aside for now.

Author: dmitryax

.chloggen/type-aliases.yaml

@@ -0,0 +1,20 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/otlp)
+component: all
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add support for deprecated component type aliases
+
+# One or more tracking issues or pull requests related to the change
+issues: [14208]
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [api]

cmd/builder/internal/builder/templates/components.go.tmpl

@@ -3,6 +3,8 @@
 package main
 
 import (
+	"fmt"
+
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/connector"
 	"go.opentelemetry.io/collector/exporter"
@@ -28,6 +30,24 @@ import (
 	{{- end}}
 )
 
+type aliasProvider interface{ DeprecatedAlias() component.Type }
+
+func expandWithAliases[T component.Factory](factories map[component.Type]T, modules map[component.Type]string, componentKind string) error {
+	for compType, factory := range factories {
+		if ap, ok := any(factory).(aliasProvider); ok {
+			alias := ap.DeprecatedAlias()
+			if alias.String() != "" {
+				if _, exists := factories[alias]; exists {
+					return fmt.Errorf("deprecated %s alias %q conflicts with existing factory", componentKind, alias)
+				}
+				factories[alias] = factory
+                modules[alias] = modules[compType]
+			}
+		}
+	}
+	return nil
+}
+
 func components() (otelcol.Factories, error) {
 	var err error
 	factories := otelcol.Factories{
@@ -59,6 +79,9 @@ func components() (otelcol.Factories, error) {
 	{{- range .Receivers}}
 	factories.ReceiverModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
 	{{- end}}
+	if err = expandWithAliases(factories.Receivers, factories.ReceiverModules, "receiver"); err != nil {
+		return otelcol.Factories{}, err
+	}
 
 	factories.Exporters, err = otelcol.MakeFactoryMap[exporter.Factory](
 		{{- range .Exporters}}
@@ -72,6 +95,9 @@ func components() (otelcol.Factories, error) {
 	{{- range .Exporters}}
 	factories.ExporterModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
 	{{- end}}
+	if err = expandWithAliases(factories.Exporters, factories.ExporterModules, "exporter"); err != nil {
+		return otelcol.Factories{}, err
+	}
 
 	factories.Processors, err = otelcol.MakeFactoryMap[processor.Factory](
 		{{- range .Processors}}
@@ -85,6 +111,9 @@ func components() (otelcol.Factories, error) {
 	{{- range .Processors}}
 	factories.ProcessorModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
 	{{- end}}
+	if err = expandWithAliases(factories.Processors, factories.ProcessorModules, "processor"); err != nil {
+		return otelcol.Factories{}, err
+	}
 
 	factories.Connectors, err = otelcol.MakeFactoryMap[connector.Factory](
 		{{- range .Connectors}}
@@ -98,6 +127,9 @@ func components() (otelcol.Factories, error) {
 	{{- range .Connectors}}
 	factories.ConnectorModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
 	{{- end}}
+	if err = expandWithAliases(factories.Connectors, factories.ConnectorModules, "connector"); err != nil {
+		return otelcol.Factories{}, err
+	}
 
 	return factories, nil
 }

cmd/otelcorecol/components.go

@@ -213,6 +213,14 @@ func WithProfilesToLogs(createProfilesToLogs CreateProfilesToLogsFunc, sl compon
 	})
 }
 
+// WithDeprecatedTypeAlias configures a deprecated type alias for the connector. Only one alias is supported per connector.
+// When the alias is used in configuration, a deprecation warning is automatically logged.
+func WithDeprecatedTypeAlias(alias component.Type) FactoryOption {
+	return factoryOptionFunc(func(o *factoryOpts) {
+		o.deprecatedAlias = alias
+	})
+}
+
 // factory implements the Factory interface.
 type factory struct {
 	connector.Factory
@@ -234,6 +242,11 @@ type factory struct {
 	profilesToTracesStabilityLevel   component.StabilityLevel
 	profilesToMetricsStabilityLevel  component.StabilityLevel
 	profilesToLogsStabilityLevel     component.StabilityLevel
+	deprecatedAlias                  component.Type
+}
+
+func (f *factory) DeprecatedAlias() component.Type {
+	return f.deprecatedAlias
 }
 
 func (f *factory) TracesToProfilesStability() component.StabilityLevel {

connector/xconnector/connector.go

@@ -146,3 +146,23 @@ func createProfilesToMetrics(context.Context, connector.Settings, component.Conf
 func createProfilesToLogs(context.Context, connector.Settings, component.Config, consumer.Logs) (Profiles, error) {
 	return nopInstance, nil
 }
+
+func TestNewFactoryWithDeprecatedAlias(t *testing.T) {
+	testType := component.MustNewType("newname")
+	aliasType := component.MustNewType("oldname")
+	defaultCfg := struct{}{}
+
+	factory := NewFactory(
+		testType,
+		func() component.Config { return &defaultCfg },
+		WithProfilesToProfiles(createProfilesToProfiles, component.StabilityLevelAlpha),
+		WithDeprecatedTypeAlias(aliasType),
+	)
+
+	assert.Equal(t, testType, factory.Type())
+	assert.Equal(t, aliasType, factory.DeprecatedAlias())
+	assert.EqualValues(t, &defaultCfg, factory.CreateDefaultConfig())
+
+	_, err := factory.CreateProfilesToProfiles(context.Background(), connector.Settings{ID: component.MustNewIDWithName("type", "name")}, &defaultCfg, consumertest.NewNop())
+	require.NoError(t, err)
+}

connector/xconnector/connector_test.go

@@ -81,16 +81,29 @@ func WithProfiles(createProfiles CreateProfilesFunc, sl component.StabilityLevel
 	})
 }
 
+// WithDeprecatedTypeAlias configures a deprecated type alias for the exporter. Only one alias is supported per exporter.
+// When the alias is used in configuration, a deprecation warning is automatically logged.
+func WithDeprecatedTypeAlias(alias component.Type) FactoryOption {
+	return factoryOptionFunc(func(o *factoryOpts) {
+		o.deprecatedAlias = alias
+	})
+}
+
 type factory struct {
 	exporter.Factory
 	createProfilesFunc     CreateProfilesFunc
 	profilesStabilityLevel component.StabilityLevel
+	deprecatedAlias        component.Type
 }
 
 func (f *factory) ProfilesStability() component.StabilityLevel {
 	return f.profilesStabilityLevel
 }
 
+func (f *factory) DeprecatedAlias() component.Type {
+	return f.deprecatedAlias
+}
+
 func (f *factory) CreateProfiles(ctx context.Context, set exporter.Settings, cfg component.Config) (Profiles, error) {
 	if f.createProfilesFunc == nil {
 		return nil, pipeline.ErrSignalNotSupported

exporter/xexporter/exporter.go

@@ -53,3 +53,23 @@ type nop struct {
 func createProfiles(context.Context, exporter.Settings, component.Config) (Profiles, error) {
 	return nopInstance, nil
 }
+
+func TestNewFactoryWithDeprecatedAlias(t *testing.T) {
+	testType := component.MustNewType("newname")
+	aliasType := component.MustNewType("oldname")
+	defaultCfg := struct{}{}
+
+	factory := NewFactory(
+		testType,
+		func() component.Config { return &defaultCfg },
+		WithProfiles(createProfiles, component.StabilityLevelAlpha),
+		WithDeprecatedTypeAlias(aliasType),
+	)
+
+	assert.Equal(t, testType, factory.Type())
+	assert.Equal(t, aliasType, factory.DeprecatedAlias())
+	assert.EqualValues(t, &defaultCfg, factory.CreateDefaultConfig())
+
+	_, err := factory.CreateProfiles(context.Background(), exporter.Settings{ID: component.MustNewID("newname")}, &defaultCfg)
+	require.NoError(t, err)
+}

exporter/xexporter/exporter_test.go

@@ -56,12 +56,17 @@ type factory struct {
 	processor.Factory
 	createProfilesFunc     CreateProfilesFunc
 	profilesStabilityLevel component.StabilityLevel
+	deprecatedAlias        component.Type
 }
 
 func (f factory) ProfilesStability() component.StabilityLevel {
 	return f.profilesStabilityLevel
 }
 
+func (f factory) DeprecatedAlias() component.Type {
+	return f.deprecatedAlias
+}
+
 func (f factory) CreateProfiles(ctx context.Context, set processor.Settings, cfg component.Config, next xconsumer.Profiles) (Profiles, error) {
 	if f.createProfilesFunc == nil {
 		return nil, pipeline.ErrSignalNotSupported
@@ -106,6 +111,14 @@ func WithProfiles(createProfiles CreateProfilesFunc, sl component.StabilityLevel
 	})
 }
 
+// WithDeprecatedTypeAlias configures a deprecated type alias for the processor. Only one alias is supported per processor.
+// When the alias is used in configuration, a deprecation warning is automatically logged.
+func WithDeprecatedTypeAlias(alias component.Type) FactoryOption {
+	return factoryOptionFunc(func(o *factoryOpts) {
+		o.deprecatedAlias = alias
+	})
+}
+
 // NewFactory returns a Factory.
 func NewFactory(cfgType component.Type, createDefaultConfig component.CreateDefaultConfigFunc, options ...FactoryOption) Factory {
 	opts := factoryOpts{factory: &factory{}}

processor/xprocessor/processor.go

@@ -54,3 +54,23 @@ type nopProcessor struct {
 func createProfiles(context.Context, processor.Settings, component.Config, xconsumer.Profiles) (Profiles, error) {
 	return nopInstance, nil
 }
+
+func TestNewFactoryWithDeprecatedAlias(t *testing.T) {
+	testType := component.MustNewType("newname")
+	aliasType := component.MustNewType("oldname")
+	defaultCfg := struct{}{}
+
+	factory := NewFactory(
+		testType,
+		func() component.Config { return &defaultCfg },
+		WithProfiles(createProfiles, component.StabilityLevelAlpha),
+		WithDeprecatedTypeAlias(aliasType),
+	)
+
+	assert.Equal(t, testType, factory.Type())
+	assert.Equal(t, aliasType, factory.DeprecatedAlias())
+	assert.EqualValues(t, &defaultCfg, factory.CreateDefaultConfig())
+
+	_, err := factory.CreateProfiles(context.Background(), processor.Settings{ID: component.MustNewID("newname")}, &defaultCfg, consumertest.NewNop())
+	require.NoError(t, err)
+}

processor/xprocessor/processor_test.go

@@ -58,12 +58,17 @@ type factory struct {
 	receiver.Factory
 	createProfilesFunc     CreateProfilesFunc
 	profilesStabilityLevel component.StabilityLevel
+	deprecatedAlias        component.Type
 }
 
 func (f *factory) ProfilesStability() component.StabilityLevel {
 	return f.profilesStabilityLevel
 }
 
+func (f *factory) DeprecatedAlias() component.Type {
+	return f.deprecatedAlias
+}
+
 func (f *factory) CreateProfiles(ctx context.Context, set receiver.Settings, cfg component.Config, next xconsumer.Profiles) (Profiles, error) {
 	if f.createProfilesFunc == nil {
 		return nil, pipeline.ErrSignalNotSupported
@@ -108,6 +113,14 @@ func WithProfiles(createProfiles CreateProfilesFunc, sl component.StabilityLevel
 	})
 }
 
+// WithDeprecatedTypeAlias configures a deprecated type alias for the receiver. Only one alias is supported per receiver.
+// When the alias is used in configuration, a deprecation warning is automatically logged.
+func WithDeprecatedTypeAlias(alias component.Type) FactoryOption {
+	return factoryOptionFunc(func(o *factoryOpts) {
+		o.deprecatedAlias = alias
+	})
+}
+
 // NewFactory returns a Factory.
 func NewFactory(cfgType component.Type, createDefaultConfig component.CreateDefaultConfigFunc, options ...FactoryOption) Factory {
 	opts := factoryOpts{factory: &factory{}}