component

package module
v0.99.0 Latest Latest
Warning

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

 Go to latest Published: Apr 22, 2024 License: Apache-2.0 Imports: 14 Imported by: 1,005

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, an extension, or a connector.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// DataTypeTraces is the data type tag for traces.
	DataTypeTraces = mustNewDataType("traces")

	// DataTypeMetrics is the data type tag for metrics.
	DataTypeMetrics = mustNewDataType("metrics")

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

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

View Source 
var (
	// 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 StatusIsError added in v0.87.0 

func StatusIsError(status Status) bool

StatusIsError returns true for error statuses (e.g. StatusRecoverableError, StatusPermanentError, or StatusFatalError)

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

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

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

func MustNewID(typeVal string) ID

MustNewID builds a Type and returns a new ID with the given Type and empty name. See MustNewType to check the valid values of typeVal.

func MustNewIDWithName added in v0.94.0 

func MustNewIDWithName(typeVal string, nameVal string) ID

MustNewIDWithName builds a Type and returns a new ID with the given Type and name. See MustNewType to check the valid values of typeVal.

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

type InstanceID struct {
	ID          ID
	Kind        Kind
	PipelineIDs map[ID]struct{}
}

InstanceID uniquely identifies a component instance

type Kind 

type Kind int

Kind represents component kinds. 

const (
	KindReceiver Kind
	KindProcessor
	KindExporter
	KindExtension
	KindConnector
)

func (Kind) String added in v0.89.0 

func (k Kind) String() string

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

type Status int32
const (
	StatusNone Status = iota
	StatusStarting
	StatusOK
	StatusRecoverableError
	StatusPermanentError
	StatusFatalError
	StatusStopping
	StatusStopped
)

Enumeration of possible component statuses

func AggregateStatus added in v0.87.0 

func AggregateStatus[K comparable](eventMap map[K]*StatusEvent) Status

AggregateStatus will derive a status for the given input using the following rules in order:

  1. If all instances have the same status, there is nothing to aggregate, return it.
  2. If any instance encounters a fatal error, the component is in a Fatal Error state.
  3. If any instance is in a Permanent Error state, the component status is Permanent Error.
  4. If any instance is Stopping, the component is in a Stopping state.
  5. An instance is Stopped, but not all instances are Stopped, we must be in the process of Stopping the component.
  6. If any instance is in a Recoverable Error state, the component status is Recoverable Error.
  7. By process of elimination, the only remaining state is starting.

func (Status) String added in v0.87.0 

func (s Status) String() string

String returns a string representation of a Status

type StatusEvent added in v0.87.0 

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

StatusEvent contains a status and timestamp, and can contain an error

func AggregateStatusEvent added in v0.87.0 

func AggregateStatusEvent[K comparable](eventMap map[K]*StatusEvent) *StatusEvent

AggregateStatusEvent returns a status event where:

  • The status is set to the aggregate status of the events in the eventMap
  • The timestamp is set to the latest timestamp of the events in the eventMap
  • For an error status, the event will have same error as the most current event of the same error type from the eventMap

func NewFatalErrorEvent added in v0.87.0 

func NewFatalErrorEvent(err error) *StatusEvent

NewFatalErrorEvent creates and returns a StatusEvent with StatusFatalError, the specified error, and a timestamp set to time.Now().

func NewPermanentErrorEvent added in v0.87.0 

func NewPermanentErrorEvent(err error) *StatusEvent

NewPermanentErrorEvent creates and returns a StatusEvent with StatusPermanentError, the specified error, and a timestamp set to time.Now().

func NewRecoverableErrorEvent added in v0.87.0 

func NewRecoverableErrorEvent(err error) *StatusEvent

NewRecoverableErrorEvent creates and returns a StatusEvent with StatusRecoverableError, the specified error, and a timestamp set to time.Now().

func NewStatusEvent added in v0.87.0 

func NewStatusEvent(status Status) *StatusEvent

NewStatusEvent creates and returns a StatusEvent with the specified status and sets the timestamp time.Now(). To set an error on the event for an error status use one of the dedicated constructors (e.g. NewRecoverableErrorEvent, NewPermanentErrorEvent, NewFatalErrorEvent)

func (*StatusEvent) Err added in v0.87.0 

func (ev *StatusEvent) Err() error

Err returns the error associated with the StatusEvent.

func (*StatusEvent) Status added in v0.87.0 

func (ev *StatusEvent) Status() Status

Status returns the Status (enum) associated with the StatusEvent

func (*StatusEvent) Timestamp added in v0.87.0 

func (ev *StatusEvent) Timestamp() time.Time

Timestamp returns the timestamp associated with the StatusEvent

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

	// ReportStatus allows a component to report runtime changes in status. The service
	// will automatically report status for a component during startup and shutdown. Components can
	// use this method to report status after start and before shutdown.
	ReportStatus func(*StatusEvent)
}

TelemetrySettings provides components with APIs to report telemetry.

Note: there is a service version of this struct, servicetelemetry.TelemetrySettings, that mirrors this struct with the exception of ReportStatus. When adding or removing anything from this struct consider whether or not the same should be done for the service version.

type Type 

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

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

func MustNewType added in v0.94.0 

func MustNewType(strType string) Type

MustNewType creates a type. It panics if the type is invalid. A type must - have at least one character, - start with an ASCII alphabetic character and - can only contain ASCII alphanumeric characters and '_'.

func NewType added in v0.94.0 

func NewType(ty string) (Type, error)

NewType creates a type. It returns an error if the type is invalid. A type must - have at least one character, - start with an ASCII alphabetic character and - can only contain ASCII alphanumeric characters and '_'.

func (Type) MarshalText added in v0.98.0 

func (t Type) MarshalText() ([]byte, error)

MarshalText marshals returns the Type name.

func (Type) String added in v0.94.0 

func (t Type) String() string

String returns the string representation of the type.

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.