component

Documentation

Overview

Package component outlines the components used in the collector and provides a foundation for the component’s creation and termination process. A component can be either a receiver, exporter, processor, or an extension.

Index

• Variables
• func UnmarshalConfig(conf *confmap.Conf, intoCfg Config) error
• func ValidateConfig(cfg Config) error
• type BuildInfo
  • func NewDefaultBuildInfo() BuildInfo
• type Component
• type Config
• type ConfigValidator
• type CreateDefaultConfigFunc
  • func (f CreateDefaultConfigFunc) CreateDefaultConfig() Config
• type DataType
• type Factory
• type Host
• type ID
  • func NewID(typeVal Type) ID
  • func NewIDWithName(typeVal Type, nameVal string) ID
  • func (id ID) MarshalText() (text []byte, err error)
  • func (id ID) Name() string
  • func (id ID) String() string
  • func (id ID) Type() Type
  • func (id *ID) UnmarshalText(text []byte) error
• type Kind
• type ShutdownFunc
  • func (f ShutdownFunc) Shutdown(ctx context.Context) error
• type StabilityLevel
  • func (sl StabilityLevel) LogMessage() string
  • func (sl StabilityLevel) String() string
• type StartFunc
  • func (f StartFunc) Start(ctx context.Context, host Host) error
• type TelemetrySettings
• type Type

Variables

var (
	// ErrNilNextConsumer can be returned by receiver, or processor Start factory funcs that create the Component if the
	// expected next Consumer is nil.
	ErrNilNextConsumer = errors.New("nil next Consumer")

	// ErrDataTypeIsNotSupported can be returned by receiver, exporter or processor factory funcs that create the
	// Component if the particular telemetry data type is not supported by the receiver, exporter or processor.
	ErrDataTypeIsNotSupported = errors.New("telemetry type is not supported")
)

Functions

func UnmarshalConfig

func UnmarshalConfig(conf *confmap.Conf, intoCfg Config) error

UnmarshalConfig helper function to UnmarshalConfig a Config. It checks if the config implements confmap.Unmarshaler and uses that if available, otherwise uses Map.UnmarshalExact, erroring if a field is nonexistent.

func ValidateConfig

func ValidateConfig(cfg Config) error

ValidateConfig validates a config, by doing this:

• Call Validate on the config itself if the config implements ConfigValidator.

Types

type BuildInfo

type BuildInfo struct {
	// Command is the executable file name, e.g. "otelcol".
	Command string

	// Description is the full name of the collector, e.g. "OpenTelemetry Collector".
	Description string

	// Version string.
	Version string
}

BuildInfo is the information that is logged at the application start and passed into each component. This information can be overridden in custom build.

func NewDefaultBuildInfo

func NewDefaultBuildInfo() BuildInfo

NewDefaultBuildInfo returns a default BuildInfo.

type Component

type Component interface {
	// Start tells the component to start. Host parameter can be used for communicating
	// with the host after Start() has already returned. If an error is returned by
	// Start() then the collector startup will be aborted.
	// If this is an exporter component it may prepare for exporting
	// by connecting to the endpoint.
	//
	// If the component needs to perform a long-running starting operation then it is recommended
	// that Start() returns quickly and the long-running operation is performed in background.
	// In that case make sure that the long-running operation does not use the context passed
	// to Start() function since that context will be cancelled soon and can abort the long-running
	// operation. Create a new context from the context.Background() for long-running operations.
	Start(ctx context.Context, host Host) error

	// Shutdown is invoked during service shutdown. After Shutdown() is called, if the component
	// accepted data in any way, it should not accept it anymore.
	//
	// This method must be safe to call:
	//   - without Start() having been called
	//   - if the component is in a shutdown state already
	//
	// If there are any background operations running by the component they must be aborted before
	// this function returns. Remember that if you started any long-running background operations from
	// the Start() method, those operations must be also cancelled. If there are any buffers in the
	// component, they should be cleared and the data sent immediately to the next component.
	//
	// The component's lifecycle is completed once the Shutdown() method returns. No other
	// methods of the component are called after that. If necessary a new component with
	// the same or different configuration may be created and started (this may happen
	// for example if we want to restart the component).
	Shutdown(ctx context.Context) error
}

Component is either a receiver, exporter, processor, or an extension.

A component's lifecycle has the following phases:

1. Creation: The component is created using its respective factory, via a Create* call.
2. Start: The component's Start method is called.
3. Running: The component is up and running.
4. Shutdown: The component's Shutdown method is called and the lifecycle is complete.

Once the lifecycle is complete it may be repeated, in which case a new component is created, starts, runs and is shutdown again.

type Config

type Config any

Config defines the configuration for a component.Component.

Implementations and/or any sub-configs (other types embedded or included in the Config implementation) MUST implement the ConfigValidator if any validation is required for that part of the configuration (e.g. check if a required field is present).

A valid implementation MUST pass the check componenttest.CheckConfigStruct (return nil error).

type ConfigValidator

type ConfigValidator interface {
	// Validate the configuration and returns an error if invalid.
	Validate() error
}

ConfigValidator defines an optional interface for configurations to implement to do validation.

type CreateDefaultConfigFunc

type CreateDefaultConfigFunc func() Config

CreateDefaultConfigFunc is the equivalent of Factory.CreateDefaultConfig().

func (CreateDefaultConfigFunc) CreateDefaultConfig

func (f CreateDefaultConfigFunc) CreateDefaultConfig() Config

CreateDefaultConfig implements Factory.CreateDefaultConfig().

type DataType

type DataType = Type

DataType is a special Type that represents the data types supported by the collector. We currently support collecting metrics, traces and logs, this can expand in the future.

const (
	// DataTypeTraces is the data type tag for traces.
	DataTypeTraces DataType = "traces"

	// DataTypeMetrics is the data type tag for metrics.
	DataTypeMetrics DataType = "metrics"

	// DataTypeLogs is the data type tag for logs.
	DataTypeLogs DataType = "logs"
)

Currently supported data types. Add new data types here when new types are supported in the future.

type Factory

type Factory interface {
	// Type gets the type of the component created by this factory.
	Type() Type

	// CreateDefaultConfig creates the default configuration for the Component.
	// This method can be called multiple times depending on the pipeline
	// configuration and should not cause side-effects that prevent the creation
	// of multiple instances of the Component.
	// The object returned by this method needs to pass the checks implemented by
	// 'componenttest.CheckConfigStruct'. It is recommended to have these checks in the
	// tests of any implementation of the Factory interface.
	CreateDefaultConfig() Config
}

Factory is implemented by all Component factories.

This interface cannot be directly implemented. Implementations must use the factory helpers for the appropriate component type.

type Host

type Host interface {
	// ReportFatalError is used to report to the host that the component
	// encountered a fatal error (i.e.: an error that the instance can't recover
	// from) after its start function had already returned.
	//
	// ReportFatalError should be called by the component anytime after Component.Start() ends and
	// before Component.Shutdown() begins.
	ReportFatalError(err error)

	// GetFactory of the specified kind. Returns the factory for a component type.
	// This allows components to create other components. For example:
	//   func (r MyReceiver) Start(host component.Host) error {
	//     apacheFactory := host.GetFactory(KindReceiver,"apache").(receiver.Factory)
	//     receiver, err := apacheFactory.CreateMetrics(...)
	//     ...
	//   }
	//
	// GetFactory can be called by the component anytime after Component.Start() begins and
	// until Component.Shutdown() ends. Note that the component is responsible for destroying
	// other components that it creates.
	GetFactory(kind Kind, componentType Type) Factory

	// GetExtensions returns the map of extensions. Only enabled and created extensions will be returned.
	// Typically is used to find an extension by type or by full config name. Both cases
	// can be done by iterating the returned map. There are typically very few extensions,
	// so there are no performance implications due to iteration.
	//
	// GetExtensions can be called by the component anytime after Component.Start() begins and
	// until Component.Shutdown() ends.
	GetExtensions() map[ID]Component

	// GetExporters returns the map of exporters. Only enabled and created exporters will be returned.
	// Typically is used to find exporters by type or by full config name. Both cases
	// can be done by iterating the returned map. There are typically very few exporters,
	// so there are no performance implications due to iteration.
	// This returns a map by DataType of maps by exporter configs to the exporter instance.
	// Note that an exporter with the same name may be attached to multiple pipelines and
	// thus we may have an instance of the exporter for multiple data types.
	// This is an experimental function that may change or even be removed completely.
	//
	// GetExporters can be called by the component anytime after Component.Start() begins and
	// until Component.Shutdown() ends.
	//
	// Deprecated: [0.79.0] This function will be removed in the future.
	// Several components in the contrib repository use this function so it cannot be removed
	// before those cases are removed. In most cases, use of this function can be replaced by a
	// connector. See https://github.com/open-telemetry/opentelemetry-collector/issues/7370 and
	// https://github.com/open-telemetry/opentelemetry-collector/pull/7390#issuecomment-1483710184
	// for additional information.
	GetExporters() map[DataType]map[ID]Component
}

Host represents the entity that is hosting a Component. It is used to allow communication between the Component and its host (normally the service.Collector is the host).

type ID

type ID struct {
	// contains filtered or unexported fields
}

ID represents the identity for a component. It combines two values: * type - the Type of the component. * name - the name of that component. The component ID (combination type + name) is unique for a given component.Kind.

func NewID

func NewID(typeVal Type) ID

NewID returns a new ID with the given Type and empty name.

func NewIDWithName

func NewIDWithName(typeVal Type, nameVal string) ID

NewIDWithName returns a new ID with the given Type and name.

func (ID) MarshalText

func (id ID) MarshalText() (text []byte, err error)

MarshalText implements the encoding.TextMarshaler interface. This marshals the type and name as one string in the config.

func (ID) Name

func (id ID) Name() string

Name returns the custom name of the component.

func (ID) String

func (id ID) String() string

String returns the ID string representation as "type[/name]" format.

func (ID) Type

func (id ID) Type() Type

Type returns the type of the component.

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

type Kind

type Kind int

Kind represents component kinds.

const (
	KindReceiver Kind
	KindProcessor
	KindExporter
	KindExtension
	KindConnector
)

type ShutdownFunc

type ShutdownFunc func(context.Context) error

ShutdownFunc specifies the function invoked when the component.Component is being shutdown.

func (ShutdownFunc) Shutdown

func (f ShutdownFunc) Shutdown(ctx context.Context) error

Shutdown shuts down the component.

type StabilityLevel

type StabilityLevel int

StabilityLevel represents the stability level of the component created by the factory. The stability level is used to determine if the component should be used in production or not. For more details see: https://github.com/open-telemetry/opentelemetry-collector#stability-levels

const (
	StabilityLevelUndefined StabilityLevel = iota // skip 0, start types from 1.
	StabilityLevelUnmaintained
	StabilityLevelDeprecated
	StabilityLevelDevelopment
	StabilityLevelAlpha
	StabilityLevelBeta
	StabilityLevelStable
)

func (StabilityLevel) LogMessage

func (sl StabilityLevel) LogMessage() string

func (StabilityLevel) String

func (sl StabilityLevel) String() string

type StartFunc

type StartFunc func(context.Context, Host) error

StartFunc specifies the function invoked when the component.Component is being started.

func (StartFunc) Start

func (f StartFunc) Start(ctx context.Context, host Host) error

Start starts the component.

type TelemetrySettings

type TelemetrySettings struct {
	// Logger that the factory can use during creation and can pass to the created
	// component to be used later as well.
	Logger *zap.Logger

	// TracerProvider that the factory can pass to other instrumented third-party libraries.
	TracerProvider trace.TracerProvider

	// MeterProvider that the factory can pass to other instrumented third-party libraries.
	MeterProvider metric.MeterProvider

	// MetricsLevel controls the level of detail for metrics emitted by the collector.
	// Experimental: *NOTE* this field is experimental and may be changed or removed.
	MetricsLevel configtelemetry.Level

	// Resource contains the resource attributes for the collector's telemetry.
	Resource pcommon.Resource
}

type Type

type Type string

Type is the component type as it is used in the config.