README
¶
General Information
A receiver is how data gets into the OpenTelemetry Collector. Generally, a receiver accepts data in a specified format, translates it into the internal format and passes it to processors and exporters defined in the applicable pipelines.
This repository hosts the following receiver available in traces, metrics and logs pipelines:
The contrib repository has more receivers available in its builds.
Configuring Receivers
Receivers are configured via YAML under the top-level receivers tag. There
must be at least one enabled receiver for a configuration to be considered
valid.
The following is a sample configuration for the examplereceiver.
receivers:
# Receiver 1.
# <receiver type>:
examplereceiver:
# <setting one>: <value one>
endpoint: 1.2.3.4:8080
# ...
# Receiver 2.
# <receiver type>/<name>:
examplereceiver/settings:
# <setting two>: <value two>
endpoint: 0.0.0.0:9211
A receiver instance is referenced by its full name in other parts of the config, such as in pipelines. A full name consists of the receiver type, '/' and the name appended to the receiver type in the configuration. All receiver full names must be unique.
For the example above:
- Receiver 1 has full name
examplereceiver. - Receiver 2 has full name
examplereceiver/settings.
Receivers are enabled upon being added to a pipeline. For example:
service:
pipelines:
# Valid pipelines are: traces, metrics or logs
# Trace pipeline 1.
traces:
receivers: [examplereceiver, examplereceiver/settings]
processors: []
exporters: [exampleexporter]
# Trace pipeline 2.
traces/another:
receivers: [examplereceiver, examplereceiver/settings]
processors: []
exporters: [exampleexporter]
At least one receiver must be enabled per pipeline to be a valid configuration.
Documentation
¶
Overview ¶
Package receiver defines components that allows the collector to receive metrics, traces and logs.
Receiver receives data from a source (either from a remote source via network or scrapes from a local host) and pushes the data to the pipelines it is attached to by calling the nextConsumer.Consume*() function.
Error Handling ¶
The nextConsumer.Consume*() function may return an error to indicate that the data was not accepted. There are 2 types of possible errors: Permanent and non-Permanent. The receiver must check the type of the error using IsPermanent() helper.
If the error is Permanent, then the nextConsumer.Consume*() call should not be retried with the same data. This typically happens when the data cannot be serialized by the exporter that is attached to the pipeline or when the destination refuses the data because it cannot decode it. The receiver must indicate to the source from which it received the data that the received data was bad, if the receiving protocol allows to do that. In case of OTLP/HTTP for example, this means that HTTP 400 response is returned to the sender.
If the error is non-Permanent then the nextConsumer.Consume*() call should be retried with the same data. This may be done by the receiver itself, however typically it is done by the original sender, after the receiver returns a response to the sender indicating that the Collector is currently overloaded and the request must be retried. In case of OTLP/HTTP for example, this means that HTTP 429 or 503 response is returned.
Acknowledgment and Checkpointing ¶
The receivers that receive data via a network protocol that support acknowledgments MUST follow this order of operations:
- Receive data from some sender (typically from a network).
- Push received data to the pipeline by calling nextConsumer.Consume*() function.
- Acknowledge successful data receipt to the sender if Consume*() succeeded or return a failure to the sender if Consume*() returned an error.
This ensures there are strong delivery guarantees once the data is acknowledged by the Collector.
Similarly, receivers that use checkpointing to remember the position of last processed data (e.g. via storage extension) MUST store the checkpoint only AFTER the Consume*() call returns.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CreateLogsFunc ¶
CreateLogsFunc is the equivalent of Factory.CreateLogs.
type CreateMetricsFunc ¶
type CreateMetricsFunc func(context.Context, Settings, component.Config, consumer.Metrics) (Metrics, error)
CreateMetricsFunc is the equivalent of Factory.CreateMetrics.
type CreateTracesFunc ¶
type CreateTracesFunc func(context.Context, Settings, component.Config, consumer.Traces) (Traces, error)
CreateTracesFunc is the equivalent of Factory.CreateTraces.
type Factory ¶
type Factory interface {
component.Factory
// CreateTraces creates a Traces based on this config.
// If the receiver type does not support traces,
// this function returns the error [pipeline.ErrSignalNotSupported].
// Implementers can assume `next` is never nil.
CreateTraces(ctx context.Context, set Settings, cfg component.Config, next consumer.Traces) (Traces, error)
// TracesStability gets the stability level of the Traces receiver.
TracesStability() component.StabilityLevel
// CreateMetrics creates a Metrics based on this config.
// If the receiver type does not support metrics,
// this function returns the error [pipeline.ErrSignalNotSupported].
// Implementers can assume `next` is never nil.
CreateMetrics(ctx context.Context, set Settings, cfg component.Config, next consumer.Metrics) (Metrics, error)
// MetricsStability gets the stability level of the Metrics receiver.
MetricsStability() component.StabilityLevel
// CreateLogs creates a Logs based on this config.
// If the receiver type does not support logs,
// this function returns the error [pipeline.ErrSignalNotSupported].
// Implementers can assume `next` is never nil.
CreateLogs(ctx context.Context, set Settings, cfg component.Config, next consumer.Logs) (Logs, error)
// LogsStability gets the stability level of the Logs receiver.
LogsStability() component.StabilityLevel
// contains filtered or unexported methods
}
Factory is a factory interface for receivers.
This interface cannot be directly implemented. Implementations must use the NewFactory to implement it.
func NewFactory ¶
func NewFactory(cfgType component.Type, createDefaultConfig component.CreateDefaultConfigFunc, options ...FactoryOption) Factory
NewFactory returns a Factory.
type FactoryOption ¶
type FactoryOption interface {
// contains filtered or unexported methods
}
FactoryOption apply changes to Factory.
func WithLogs ¶
func WithLogs(createLogs CreateLogsFunc, sl component.StabilityLevel) FactoryOption
WithLogs overrides the default "error not supported" implementation for Factory.CreateLogs and the default "undefined" stability level.
func WithMetrics ¶
func WithMetrics(createMetrics CreateMetricsFunc, sl component.StabilityLevel) FactoryOption
WithMetrics overrides the default "error not supported" implementation for Factory.CreateMetrics and the default "undefined" stability level.
func WithTraces ¶
func WithTraces(createTraces CreateTracesFunc, sl component.StabilityLevel) FactoryOption
WithTraces overrides the default "error not supported" implementation for Factory.CreateTraces and the default "undefined" stability level.
type Logs ¶
Logs receiver receives logs. Its purpose is to translate data from any format to the collector's internal logs data format. Logs receiver feeds a consumer.Logs with data.
For example, it could be a receiver that reads syslogs and convert them into plog.Logs.
type Metrics ¶
Metrics receiver receives metrics. Its purpose is to translate data from any format to the collector's internal metrics format. Metrics receiver feeds a consumer.Metrics with data.
For example, it could be Prometheus data source which translates Prometheus metrics into pmetric.Metrics.
type Settings ¶ added in v0.103.0
type Settings struct {
// ID returns the ID of the component that will be created.
ID component.ID
component.TelemetrySettings
// BuildInfo can be used by components for informational purposes.
BuildInfo component.BuildInfo
}
Settings configures receiver creators.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
nopreceiver
module
|
|
|
otlpreceiver
module
|
|
|
receiverprofiles
module
|
|
|
receivertest
module
|
|
|
Package scrapererror provides custom error types for scrapers.
|
Package scrapererror provides custom error types for scrapers. |
|
Package scraperhelper provides utilities for scrapers.
|
Package scraperhelper provides utilities for scrapers. |