Add support for deprecated component type aliases (#14349)

Related to
#14208

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)
- 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,35 @@
+# 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) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+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