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]

.github/workflows/utils/cspell.json

@@ -125,6 +125,7 @@
       "cmux",
       "codeboten",
       "codeowners",
+      "componentalias",
       "componenterror",
       "componenthelper",
       "componentprofiles",

cmd/builder/internal/builder/main_test.go

@@ -88,6 +88,7 @@ var replaceModules = []string{
 	"/extension/zpagesextension",
 	"/extension/xextension",
 	"/featuregate",
+	"/internal/componentalias",
 	"/internal/memorylimiter",
 	"/internal/fanoutconsumer",
 	"/internal/sharedcomponent",

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

@@ -28,6 +28,20 @@ import (
 	{{- end}}
 )
 
+type aliasProvider interface{ DeprecatedAlias() component.Type }
+
+func makeModulesMap[T component.Factory](factories map[component.Type]T, modules map[component.Type]string) map[component.Type]string {
+	for compType, factory := range factories {
+		if ap, ok := any(factory).(aliasProvider); ok {
+			alias := ap.DeprecatedAlias()
+			if alias.String() != "" {
+				modules[alias] = modules[compType]
+			}
+		}
+	}
+	return modules
+}
+
 func components() (otelcol.Factories, error) {
 	var err error
 	factories := otelcol.Factories{
@@ -42,10 +56,11 @@ func components() (otelcol.Factories, error) {
 	if err != nil {
 		return otelcol.Factories{}, err
 	}
-	factories.ExtensionModules = make(map[component.Type]string, len(factories.Extensions))
-	{{- range .Extensions}}
-	factories.ExtensionModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
-	{{- end}}
+	factories.ExtensionModules = makeModulesMap(factories.Extensions, map[component.Type]string{
+		{{- range .Extensions}}
+		{{.Name}}.NewFactory().Type(): "{{.GoMod}}",
+		{{- end}}
+	})
 
 	factories.Receivers, err = otelcol.MakeFactoryMap[receiver.Factory](
 		{{- range .Receivers}}
@@ -55,10 +70,11 @@ func components() (otelcol.Factories, error) {
 	if err != nil {
 		return otelcol.Factories{}, err
 	}
-	factories.ReceiverModules = make(map[component.Type]string, len(factories.Receivers))
-	{{- range .Receivers}}
-	factories.ReceiverModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
-	{{- end}}
+	factories.ReceiverModules = makeModulesMap(factories.Receivers, map[component.Type]string{
+		{{- range .Receivers}}
+		{{.Name}}.NewFactory().Type(): "{{.GoMod}}",
+		{{- end}}
+	})
 
 	factories.Exporters, err = otelcol.MakeFactoryMap[exporter.Factory](
 		{{- range .Exporters}}
@@ -68,10 +84,11 @@ func components() (otelcol.Factories, error) {
 	if err != nil {
 		return otelcol.Factories{}, err
 	}
-	factories.ExporterModules = make(map[component.Type]string, len(factories.Exporters))
-	{{- range .Exporters}}
-	factories.ExporterModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
-	{{- end}}
+	factories.ExporterModules = makeModulesMap(factories.Exporters, map[component.Type]string{
+		{{- range .Exporters}}
+		{{.Name}}.NewFactory().Type(): "{{.GoMod}}",
+		{{- end}}
+	})
 
 	factories.Processors, err = otelcol.MakeFactoryMap[processor.Factory](
 		{{- range .Processors}}
@@ -81,10 +98,11 @@ func components() (otelcol.Factories, error) {
 	if err != nil {
 		return otelcol.Factories{}, err
 	}
-	factories.ProcessorModules = make(map[component.Type]string, len(factories.Processors))
-	{{- range .Processors}}
-	factories.ProcessorModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
-	{{- end}}
+	factories.ProcessorModules = makeModulesMap(factories.Processors, map[component.Type]string{
+		{{- range .Processors}}
+		{{.Name}}.NewFactory().Type(): "{{.GoMod}}",
+		{{- end}}
+	})
 
 	factories.Connectors, err = otelcol.MakeFactoryMap[connector.Factory](
 		{{- range .Connectors}}
@@ -94,10 +112,11 @@ func components() (otelcol.Factories, error) {
 	if err != nil {
 		return otelcol.Factories{}, err
 	}
-	factories.ConnectorModules = make(map[component.Type]string, len(factories.Connectors))
-	{{- range .Connectors}}
-	factories.ConnectorModules[{{.Name}}.NewFactory().Type()] = "{{.GoMod}}"
-	{{- end}}
+	factories.ConnectorModules = makeModulesMap(factories.Connectors, map[component.Type]string{
+		{{- range .Connectors}}
+		{{.Name}}.NewFactory().Type(): "{{.GoMod}}",
+		{{- end}}
+	})
 
 	return factories, nil
 }

cmd/mdatagen/go.mod

@@ -61,6 +61,7 @@ require (
 	go.opentelemetry.io/collector/consumer/consumererror v0.143.0 // indirect
 	go.opentelemetry.io/collector/consumer/xconsumer v0.143.0 // indirect
 	go.opentelemetry.io/collector/featuregate v1.49.0 // indirect
+	go.opentelemetry.io/collector/internal/componentalias v0.0.0-00010101000000-000000000000 // indirect
 	go.opentelemetry.io/collector/internal/fanoutconsumer v0.143.0 // indirect
 	go.opentelemetry.io/collector/pdata/pprofile v0.143.0 // indirect
 	go.opentelemetry.io/collector/pdata/testdata v0.143.0 // indirect
@@ -200,3 +201,5 @@ replace go.opentelemetry.io/collector/exporter/exporterhelper => ../../exporter/
 replace go.opentelemetry.io/collector/service/telemetry/telemetrytest => ../../service/telemetry/telemetrytest
 
 replace go.opentelemetry.io/collector/internal/testutil => ../../internal/testutil
+
+replace go.opentelemetry.io/collector/internal/componentalias => ../../internal/componentalias

cmd/otelcorecol/builder-config.yaml

@@ -89,6 +89,7 @@ replaces:
   - go.opentelemetry.io/collector/extension/xextension => ../../extension/xextension
   - go.opentelemetry.io/collector/extension/zpagesextension => ../../extension/zpagesextension
   - go.opentelemetry.io/collector/featuregate => ../../featuregate
+  - go.opentelemetry.io/collector/internal/componentalias => ../../internal/componentalias
   - go.opentelemetry.io/collector/internal/memorylimiter => ../../internal/memorylimiter
   - go.opentelemetry.io/collector/internal/fanoutconsumer => ../../internal/fanoutconsumer
   - go.opentelemetry.io/collector/internal/telemetry => ../../internal/telemetry

cmd/otelcorecol/components.go

@@ -116,6 +116,7 @@ require (
 	go.opentelemetry.io/collector/extension/extensiontest v0.143.0 // indirect
 	go.opentelemetry.io/collector/extension/xextension v0.143.0 // indirect
 	go.opentelemetry.io/collector/featuregate v1.49.0 // indirect
+	go.opentelemetry.io/collector/internal/componentalias v0.0.0-00010101000000-000000000000 // indirect
 	go.opentelemetry.io/collector/internal/fanoutconsumer v0.143.0 // indirect
 	go.opentelemetry.io/collector/internal/memorylimiter v0.143.0 // indirect
 	go.opentelemetry.io/collector/internal/sharedcomponent v0.143.0 // indirect
@@ -279,6 +280,8 @@ replace go.opentelemetry.io/collector/extension/zpagesextension => ../../extensi
 
 replace go.opentelemetry.io/collector/featuregate => ../../featuregate
 
+replace go.opentelemetry.io/collector/internal/componentalias => ../../internal/componentalias
+
 replace go.opentelemetry.io/collector/internal/memorylimiter => ../../internal/memorylimiter
 
 replace go.opentelemetry.io/collector/internal/fanoutconsumer => ../../internal/fanoutconsumer

cmd/otelcorecol/go.mod

@@ -9,6 +9,7 @@ import (
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/connector/internal"
 	"go.opentelemetry.io/collector/consumer"
+	"go.opentelemetry.io/collector/internal/componentalias"
 	"go.opentelemetry.io/collector/pipeline"
 )
 
@@ -234,6 +235,7 @@ func WithLogsToLogs(createLogsToLogs CreateLogsToLogsFunc, sl component.Stabilit
 type factory struct {
 	cfgType component.Type
 	component.CreateDefaultConfigFunc
+	componentalias.TypeAliasHolder
 
 	createTracesToTracesFunc  CreateTracesToTracesFunc
 	createTracesToMetricsFunc CreateTracesToMetricsFunc
@@ -308,8 +310,8 @@ func (f *factory) CreateTracesToTraces(ctx context.Context, set Settings, cfg co
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalTraces, pipeline.SignalTraces)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createTracesToTracesFunc(ctx, set, cfg, next)
@@ -320,8 +322,8 @@ func (f *factory) CreateTracesToMetrics(ctx context.Context, set Settings, cfg c
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalTraces, pipeline.SignalMetrics)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createTracesToMetricsFunc(ctx, set, cfg, next)
@@ -332,8 +334,8 @@ func (f *factory) CreateTracesToLogs(ctx context.Context, set Settings, cfg comp
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalTraces, pipeline.SignalLogs)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createTracesToLogsFunc(ctx, set, cfg, next)
@@ -344,8 +346,8 @@ func (f *factory) CreateMetricsToTraces(ctx context.Context, set Settings, cfg c
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalMetrics, pipeline.SignalTraces)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createMetricsToTracesFunc(ctx, set, cfg, next)
@@ -356,8 +358,8 @@ func (f *factory) CreateMetricsToMetrics(ctx context.Context, set Settings, cfg
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalMetrics, pipeline.SignalMetrics)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createMetricsToMetricsFunc(ctx, set, cfg, next)
@@ -368,8 +370,8 @@ func (f *factory) CreateMetricsToLogs(ctx context.Context, set Settings, cfg com
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalMetrics, pipeline.SignalLogs)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createMetricsToLogsFunc(ctx, set, cfg, next)
@@ -380,8 +382,8 @@ func (f *factory) CreateLogsToTraces(ctx context.Context, set Settings, cfg comp
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalLogs, pipeline.SignalTraces)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createLogsToTracesFunc(ctx, set, cfg, next)
@@ -392,8 +394,8 @@ func (f *factory) CreateLogsToMetrics(ctx context.Context, set Settings, cfg com
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalLogs, pipeline.SignalMetrics)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createLogsToMetricsFunc(ctx, set, cfg, next)
@@ -404,8 +406,8 @@ func (f *factory) CreateLogsToLogs(ctx context.Context, set Settings, cfg compon
 		return nil, internal.ErrDataTypes(set.ID, pipeline.SignalLogs, pipeline.SignalLogs)
 	}
 
-	if set.ID.Type() != f.Type() {
-		return nil, internal.ErrIDMismatch(set.ID, f.Type())
+	if err := componentalias.ValidateComponentType(f, set.ID); err != nil {
+		return nil, err
 	}
 
 	return f.createLogsToLogsFunc(ctx, set, cfg, next)
@@ -416,6 +418,7 @@ func NewFactory(cfgType component.Type, createDefaultConfig component.CreateDefa
 	f := &factory{
 		cfgType:                 cfgType,
 		CreateDefaultConfigFunc: createDefaultConfig,
+		TypeAliasHolder:         componentalias.NewTypeAliasHolder(),
 	}
 	for _, opt := range options {
 		opt.apply(f)