collector-component

OpenTelemetry Collector Component Scaffolding

Scaffold new OTel Collector components following the canonical patterns from the opentelemetry-collector-contrib repository.

Workflow

1. Determine component type: receiver, processor, exporter, connector, or extension
2. Determine signal types (traces, metrics, logs); connectors need input+output signals
3. Choose a Go module path (e.g., github.com/org/repo/receiver/myreceiver)
4. Generate the file set below
5. Run go mod tidy to resolve dependencies

File Layout

Every component follows this structure:

mycomponent/
  metadata.yaml
  doc.go
  config.go
  config_test.go
  factory.go
  factory_test.go
  <component>.go
  <component>_test.go
  go.mod
  go.sum
  README.md
  internal/metadata/    # generated by mdatagen
  testdata/             # test config fixtures

metadata.yaml

Drives code generation via mdatagen. Generates internal/metadata/ with type constants and stability levels.

type: mycomponent

status:
  class: receiver  # receiver | processor | exporter | connector | extension
  stability:
    # For receiver/processor/exporter: list signal types per stability:
    beta: [metrics]
    alpha: [traces, logs]
    # For connector: use input_to_output format:
    # alpha: [traces_to_metrics]
    # For extension:
    # alpha: [extension]
  distributions: [contrib]
  codeowners:
    active: [githubuser]

tests:
  config:
    # Key-value pairs matching Config struct fields for lifecycle tests

doc.go

// Package mycomponent ...
package mycomponent

//go:generate mdatagen metadata.yaml

config.go Pattern

package mycomponent

import "go.opentelemetry.io/collector/confmap/xconfmap"

var _ xconfmap.Validator = (*Config)(nil)

type Config struct {
    Field string `mapstructure:"field"`
}

func (c *Config) Validate() error {
    // Return non-nil for invalid config
    return nil
}

Use mapstructure tags for all fields. Implement xconfmap.Validator for validation.

Factory Patterns Per Component Type

Each component type has a different factory signature. Consult the appropriate reference:

• Receiver: See references/receiver.md: receives a consumer in create funcs, does NOT embed consumer
• Processor: See references/processor.md: use processorhelper for the common case
• Exporter: See references/exporter.md: NO next consumer param (terminal), use exporterhelper for retry/queue/timeout
• Connector: See references/connector.md: bridges two pipelines, up to 9 signal combinations
• Extension: See references/extension.md: simplest type, positional factory args (no variadic options)

Key API Differences

	Receiver	Processor	Exporter	Connector	Extension
Next consumer in Create?	Yes	Yes	No	Yes	No
Embeds consumer?	No	Yes	Yes	Yes	No
NewFactory style	Variadic opts	Variadic opts	Variadic opts	Variadic opts	Positional
Helper package	receiverhelper	processorhelper	exporterhelper	none	none

go.mod

Use these module paths (adjust version to latest):

go.opentelemetry.io/collector/component        v1.x
go.opentelemetry.io/collector/consumer         v1.x
go.opentelemetry.io/collector/confmap          v1.x
go.opentelemetry.io/collector/pdata            v1.x
go.opentelemetry.io/collector/receiver         v0.14x  # for receivers
go.opentelemetry.io/collector/processor        v0.14x  # for processors
go.opentelemetry.io/collector/exporter         v0.14x  # for exporters
go.opentelemetry.io/collector/connector        v0.14x  # for connectors
go.opentelemetry.io/collector/extension        v0.14x  # for extensions

OCB Integration

Once the component module is ready, add it to builder-config.yaml:

receivers:
  - gomod: github.com/org/repo/receiver/myreceiver v0.1.0

# For local development:
replaces:
  - github.com/org/repo/receiver/myreceiver => ../receiver/myreceiver

Then build: builder --config=builder-config.yaml