component

package module
v0.68.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2022 License: Apache-2.0 Imports: 12 Imported by: 1,007

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

Constants

This section is empty.

Variables

View Source 
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 MakeProcessorFactoryMap deprecated 

func MakeProcessorFactoryMap(factories ...ProcessorFactory) (map[Type]ProcessorFactory, error)

Deprecated: [v0.68.0] use processor.MakeFactoryMap

func UnmarshalConfig added in v0.67.0 

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 interface{}

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 added in v0.67.0 

type CreateDefaultConfigFunc func() Config

CreateDefaultConfigFunc is the equivalent of Factory.CreateDefaultConfig().

func (CreateDefaultConfigFunc) CreateDefaultConfig added in v0.67.0 

func (f CreateDefaultConfigFunc) CreateDefaultConfig() Config

CreateDefaultConfig implements Factory.CreateDefaultConfig().

type CreateLogsProcessorFunc deprecated 

type CreateLogsProcessorFunc func(context.Context, ProcessorCreateSettings, Config, consumer.Logs) (LogsProcessor, error)

Deprecated: [v0.68.0] use processor.CreateLogsFunc.

func (CreateLogsProcessorFunc) CreateLogsProcessor 

func (f CreateLogsProcessorFunc) CreateLogsProcessor(
	ctx context.Context,
	set ProcessorCreateSettings,
	cfg Config,
	nextConsumer consumer.Logs,
) (LogsProcessor, error)

CreateLogsProcessor implements ProcessorFactory.CreateLogsProcessor().

type CreateMetricsProcessorFunc deprecated 

type CreateMetricsProcessorFunc func(context.Context, ProcessorCreateSettings, Config, consumer.Metrics) (MetricsProcessor, error)

Deprecated: [v0.68.0] use processor.CreateMetricsFunc.

func (CreateMetricsProcessorFunc) CreateMetricsProcessor 

func (f CreateMetricsProcessorFunc) CreateMetricsProcessor(
	ctx context.Context,
	set ProcessorCreateSettings,
	cfg Config,
	nextConsumer consumer.Metrics,
) (MetricsProcessor, error)

CreateMetricsProcessor implements ProcessorFactory.CreateMetricsProcessor().

type CreateTracesProcessorFunc deprecated 

type CreateTracesProcessorFunc func(context.Context, ProcessorCreateSettings, Config, consumer.Traces) (TracesProcessor, error)

Deprecated: [v0.68.0] use processor.CreateTracesFunc.

func (CreateTracesProcessorFunc) CreateTracesProcessor 

func (f CreateTracesProcessorFunc) CreateTracesProcessor(
	ctx context.Context,
	set ProcessorCreateSettings,
	cfg Config,
	nextConsumer consumer.Traces) (TracesProcessor, error)

CreateTracesProcessor implements ProcessorFactory.CreateTracesProcessor().

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 ExporterCreateSettings deprecated 

type ExporterCreateSettings struct {
	// ID returns the ID of the component that will be created.
	ID ID

	TelemetrySettings

	// BuildInfo can be used by components for informational purposes
	BuildInfo BuildInfo
}

Deprecated: [v0.67.0] use exporter.CreateSettings.

type ExporterFactory deprecated 

type ExporterFactory interface {
	Factory

	// CreateTracesExporter creates a TracesExporter based on this config.
	// If the exporter type does not support tracing or if the config is not valid,
	// an error will be returned instead.
	CreateTracesExporter(ctx context.Context, set ExporterCreateSettings, cfg Config) (TracesExporter, error)

	// TracesExporterStability gets the stability level of the TracesExporter.
	TracesExporterStability() StabilityLevel

	// CreateMetricsExporter creates a MetricsExporter based on this config.
	// If the exporter type does not support metrics or if the config is not valid,
	// an error will be returned instead.
	CreateMetricsExporter(ctx context.Context, set ExporterCreateSettings, cfg Config) (MetricsExporter, error)

	// MetricsExporterStability gets the stability level of the MetricsExporter.
	MetricsExporterStability() StabilityLevel

	// CreateLogsExporter creates a LogsExporter based on the config.
	// If the exporter type does not support logs or if the config is not valid,
	// an error will be returned instead.
	CreateLogsExporter(ctx context.Context, set ExporterCreateSettings, cfg Config) (LogsExporter, error)

	// LogsExporterStability gets the stability level of the LogsExporter.
	LogsExporterStability() StabilityLevel
}

Deprecated: [v0.67.0] use exporter.Factory.

type Extension deprecated 

type Extension = Component

Deprecated: [v0.67.0] use extension.Extension.

type ExtensionCreateSettings deprecated 

type ExtensionCreateSettings struct {
	// ID returns the ID of the component that will be created.
	ID ID

	TelemetrySettings

	// BuildInfo can be used by components for informational purposes
	BuildInfo BuildInfo
}

Deprecated: [v0.67.0] use extension.CreateSettings.

type ExtensionFactory deprecated 

type ExtensionFactory interface {
	Factory

	// CreateExtension creates an extension based on the given config.
	CreateExtension(ctx context.Context, set ExtensionCreateSettings, cfg Config) (Extension, error)

	// ExtensionStability gets the stability level of the Extension.
	ExtensionStability() StabilityLevel
}

Deprecated: [v0.67.0] use extension.Factory.

type Factories deprecated 

type Factories struct {
	// Receivers maps receiver type names in the config to the respective factory.
	Receivers map[Type]ReceiverFactory

	// Processors maps processor type names in the config to the respective factory.
	Processors map[Type]ProcessorFactory

	// Exporters maps exporter type names in the config to the respective factory.
	Exporters map[Type]ExporterFactory

	// Extensions maps extension type names in the config to the respective factory.
	Extensions map[Type]ExtensionFactory
}

Deprecated: [v0.68.0] use otelcol.Factories.

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
	// contains filtered or unexported methods
}

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.
	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 LogsExporter deprecated 

type LogsExporter interface {
	Component
	consumer.Logs
}

Deprecated: [v0.67.0] use exporter.Logs.

type LogsProcessor deprecated 

type LogsProcessor interface {
	Component
	consumer.Logs
}

Deprecated: [v0.68.0] use processor.Logs.

type LogsReceiver deprecated 

type LogsReceiver interface {
	Component
}

Deprecated: [v0.67.0] use receiver.Logs.

type MetricsExporter deprecated 

type MetricsExporter interface {
	Component
	consumer.Metrics
}

Deprecated: [v0.67.0] use exporter.Metrics.

type MetricsProcessor deprecated 

type MetricsProcessor interface {
	Component
	consumer.Metrics
}

Deprecated: [v0.68.0] use processor.Metrics.

type MetricsReceiver deprecated 

type MetricsReceiver interface {
	Component
}

Deprecated: [v0.67.0] use receiver.Metrics.

type ProcessorCreateSettings deprecated 

type ProcessorCreateSettings struct {
	// ID returns the ID of the component that will be created.
	ID ID

	TelemetrySettings

	// BuildInfo can be used by components for informational purposes
	BuildInfo BuildInfo
}

Deprecated: [v0.68.0] use processor.CreateSettings.

type ProcessorFactory deprecated 

type ProcessorFactory interface {
	Factory

	// CreateTracesProcessor creates a TracesProcessor based on this config.
	// If the processor type does not support tracing or if the config is not valid,
	// an error will be returned instead.
	CreateTracesProcessor(ctx context.Context, set ProcessorCreateSettings, cfg Config, nextConsumer consumer.Traces) (TracesProcessor, error)

	// TracesProcessorStability gets the stability level of the TracesProcessor.
	TracesProcessorStability() StabilityLevel

	// CreateMetricsProcessor creates a MetricsProcessor based on this config.
	// If the processor type does not support metrics or if the config is not valid,
	// an error will be returned instead.
	CreateMetricsProcessor(ctx context.Context, set ProcessorCreateSettings, cfg Config, nextConsumer consumer.Metrics) (MetricsProcessor, error)

	// MetricsProcessorStability gets the stability level of the MetricsProcessor.
	MetricsProcessorStability() StabilityLevel

	// CreateLogsProcessor creates a LogsProcessor based on the config.
	// If the processor type does not support logs or if the config is not valid,
	// an error will be returned instead.
	CreateLogsProcessor(ctx context.Context, set ProcessorCreateSettings, cfg Config, nextConsumer consumer.Logs) (LogsProcessor, error)

	// LogsProcessorStability gets the stability level of the LogsProcessor.
	LogsProcessorStability() StabilityLevel
}

Deprecated: [v0.68.0] use processor.Factory.

func NewProcessorFactory deprecated 

func NewProcessorFactory(cfgType Type, createDefaultConfig CreateDefaultConfigFunc, options ...ProcessorFactoryOption) ProcessorFactory

Deprecated: [v0.68.0] use processor.NewFactory.

type ProcessorFactoryOption deprecated 

type ProcessorFactoryOption interface {
	// contains filtered or unexported methods
}

Deprecated: [v0.68.0] use processor.FactoryOption.

func WithLogsProcessor deprecated 

func WithLogsProcessor(createLogsProcessor CreateLogsProcessorFunc, sl StabilityLevel) ProcessorFactoryOption

Deprecated: [v0.68.0] use processor.WithLogs.

func WithMetricsProcessor deprecated 

func WithMetricsProcessor(createMetricsProcessor CreateMetricsProcessorFunc, sl StabilityLevel) ProcessorFactoryOption

Deprecated: [v0.68.0] use processor.WithMetrics.

func WithTracesProcessor deprecated 

func WithTracesProcessor(createTracesProcessor CreateTracesProcessorFunc, sl StabilityLevel) ProcessorFactoryOption

Deprecated: [v0.68.0] use processor.WithTraces.

type ReceiverCreateSettings deprecated 

type ReceiverCreateSettings struct {
	// ID returns the ID of the component that will be created.
	ID ID

	TelemetrySettings

	// BuildInfo can be used by components for informational purposes.
	BuildInfo BuildInfo
}

Deprecated: [v0.67.0] use receiver.CreateSettings.

type ReceiverFactory deprecated 

type ReceiverFactory interface {
	Factory

	// CreateTracesReceiver creates a TracesReceiver based on this config.
	// If the receiver type does not support tracing or if the config is not valid
	// an error will be returned instead.
	CreateTracesReceiver(ctx context.Context, set ReceiverCreateSettings, cfg Config, nextConsumer consumer.Traces) (TracesReceiver, error)

	// TracesReceiverStability gets the stability level of the TracesReceiver.
	TracesReceiverStability() StabilityLevel

	// CreateMetricsReceiver creates a MetricsReceiver based on this config.
	// If the receiver type does not support metrics or if the config is not valid
	// an error will be returned instead.
	CreateMetricsReceiver(ctx context.Context, set ReceiverCreateSettings, cfg Config, nextConsumer consumer.Metrics) (MetricsReceiver, error)

	// MetricsReceiverStability gets the stability level of the MetricsReceiver.
	MetricsReceiverStability() StabilityLevel

	// CreateLogsReceiver creates a LogsReceiver based on this config.
	// If the receiver type does not support the data type or if the config is not valid
	// an error will be returned instead.
	CreateLogsReceiver(ctx context.Context, set ReceiverCreateSettings, cfg Config, nextConsumer consumer.Logs) (LogsReceiver, error)

	// LogsReceiverStability gets the stability level of the LogsReceiver.
	LogsReceiverStability() StabilityLevel
}

Deprecated: [v0.67.0] use receivrer.Factory.

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
}

type TracesExporter deprecated 

type TracesExporter interface {
	Component
	consumer.Traces
}

Deprecated: [v0.67.0] use exporter.Traces.

type TracesProcessor deprecated 

type TracesProcessor interface {
	Component
	consumer.Traces
}

Deprecated: [v0.68.0] use processor.Traces.

type TracesReceiver deprecated 

type TracesReceiver interface {
	Component
}

Deprecated: [v0.67.0] use receiver.Traces.

type Type 

type Type string

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

Source Files

View all Source files

Directories

Path Synopsis
Package componenttest define types and functions used to help test packages implementing the component package interfaces.
 Package componenttest define types and functions used to help test packages implementing the component package interfaces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.