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,36 @@
+# 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
+
+# Optional: the name of a top-level section that the subtext will appear under, preceded by "Subtext:".
+# If not specified, the entry will not have a subtext section.
+# Please be careful not to use internal or API names that are not relevant to end users. For example, please use "myreceiverexporter" instead of "configpb".
+# If the entire description is short and no additional explanation is needed (less than ~25 words), do not use a subtext section.
+subtext: |
+  To add a deprecated type alias to a component factory, use the `WithDeprecatedTypeAlias` option.
+  ```go
+  return xexporter.NewFactory(
+      metadata.Type,
+      createDefaultConfig,
+      xexporter.WithTraces(createTracesExporter, metadata.TracesStability),
+      xexporter.WithDeprecatedTypeAlias("old_component_name"),
+  )
+  ```
+  When the alias is used in configuration, a deprecation warning will be automatically logged, and the component will function normally using the original implementation.
+
+# 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