receiver

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.

Available trace receivers (sorted alphabetically):

• OTLP Receiver

Available metric receivers (sorted alphabetically):

• OTLP Receiver

Available log receivers (sorted alphabetically):

• OTLP Receiver

The contrib repository has more receivers that can be added to custom builds of the collector.

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 may 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 Handling

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.

Index

• func MakeFactoryMap(factories ...Factory) (map[component.Type]Factory, error)
• type Builder
  • func NewBuilder(cfgs map[component.ID]component.Config, factories map[component.Type]Factory) *Builder
  • func (b *Builder) CreateLogs(ctx context.Context, set CreateSettings, next consumer.Logs) (Logs, error)
  • func (b *Builder) CreateMetrics(ctx context.Context, set CreateSettings, next consumer.Metrics) (Metrics, error)
  • func (b *Builder) CreateTraces(ctx context.Context, set CreateSettings, next consumer.Traces) (Traces, error)
  • func (b *Builder) Factory(componentType component.Type) component.Factory
• type CreateLogsFunc
  • func (f CreateLogsFunc) CreateLogsReceiver(ctx context.Context, set CreateSettings, cfg component.Config, ...) (Logs, error)
• type CreateMetricsFunc
  • func (f CreateMetricsFunc) CreateMetricsReceiver(ctx context.Context, set CreateSettings, cfg component.Config, ...) (Metrics, error)
• type CreateSettings
• type CreateTracesFunc
  • func (f CreateTracesFunc) CreateTracesReceiver(ctx context.Context, set CreateSettings, cfg component.Config, ...) (Traces, error)
• type Factory
  • func NewFactory(cfgType component.Type, createDefaultConfig component.CreateDefaultConfigFunc, ...) Factory
• type FactoryOption
  • func WithLogs(createLogsReceiver CreateLogsFunc, sl component.StabilityLevel) FactoryOption
  • func WithMetrics(createMetricsReceiver CreateMetricsFunc, sl component.StabilityLevel) FactoryOption
  • func WithTraces(createTracesReceiver CreateTracesFunc, sl component.StabilityLevel) FactoryOption
• type Logs
• type Metrics
• type Traces

Functions

func MakeFactoryMap

func MakeFactoryMap(factories ...Factory) (map[component.Type]Factory, error)

MakeFactoryMap takes a list of receiver factories and returns a map with factory type as keys. It returns a non-nil error when there are factories with duplicate type.

Types

type Builder

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

Builder receiver is a helper struct that given a set of Configs and Factories helps with creating receivers.

func NewBuilder

func NewBuilder(cfgs map[component.ID]component.Config, factories map[component.Type]Factory) *Builder

NewBuilder creates a new receiver.Builder to help with creating components form a set of configs and factories.

func (*Builder) CreateLogs

func (b *Builder) CreateLogs(ctx context.Context, set CreateSettings, next consumer.Logs) (Logs, error)

CreateLogs creates a Logs receiver based on the settings and config.

func (*Builder) CreateMetrics

func (b *Builder) CreateMetrics(ctx context.Context, set CreateSettings, next consumer.Metrics) (Metrics, error)

CreateMetrics creates a Metrics receiver based on the settings and config.

func (*Builder) CreateTraces

func (b *Builder) CreateTraces(ctx context.Context, set CreateSettings, next consumer.Traces) (Traces, error)

CreateTraces creates a Traces receiver based on the settings and config.

func (*Builder) Factory

func (b *Builder) Factory(componentType component.Type) component.Factory

type CreateLogsFunc

type CreateLogsFunc func(context.Context, CreateSettings, component.Config, consumer.Logs) (Logs, error)

CreateLogsFunc is the equivalent of ReceiverFactory.CreateLogsReceiver().

func (CreateLogsFunc) CreateLogsReceiver

func (f CreateLogsFunc) CreateLogsReceiver(
	ctx context.Context,
	set CreateSettings,
	cfg component.Config,
	nextConsumer consumer.Logs,
) (Logs, error)

CreateLogsReceiver implements Factory.CreateLogsReceiver().

type CreateMetricsFunc

type CreateMetricsFunc func(context.Context, CreateSettings, component.Config, consumer.Metrics) (Metrics, error)

CreateMetricsFunc is the equivalent of Factory.CreateMetrics.

func (CreateMetricsFunc) CreateMetricsReceiver

func (f CreateMetricsFunc) CreateMetricsReceiver(
	ctx context.Context,
	set CreateSettings,
	cfg component.Config,
	nextConsumer consumer.Metrics,
) (Metrics, error)

CreateMetricsReceiver implements Factory.CreateMetricsReceiver().

type CreateSettings

type CreateSettings = component.ReceiverCreateSettings //nolint:staticcheck

CreateSettings configures Receiver creators.

type CreateTracesFunc

type CreateTracesFunc func(context.Context, CreateSettings, component.Config, consumer.Traces) (Traces, error)

CreateTracesFunc is the equivalent of Factory.CreateTraces.

func (CreateTracesFunc) CreateTracesReceiver

func (f CreateTracesFunc) CreateTracesReceiver(
	ctx context.Context,
	set CreateSettings,
	cfg component.Config,
	nextConsumer consumer.Traces) (Traces, error)

CreateTracesReceiver implements Factory.CreateTracesReceiver().

type Factory

type Factory = component.ReceiverFactory //nolint:staticcheck

Factory is factory interface for receivers.

This interface cannot be directly implemented. Implementations must use the NewReceiverFactory 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 ReceiverOptions.

func WithLogs

func WithLogs(createLogsReceiver CreateLogsFunc, sl component.StabilityLevel) FactoryOption

WithLogs overrides the default "error not supported" implementation for CreateLogsReceiver and the default "undefined" stability level.

func WithMetrics

func WithMetrics(createMetricsReceiver CreateMetricsFunc, sl component.StabilityLevel) FactoryOption

WithMetrics overrides the default "error not supported" implementation for CreateMetricsReceiver and the default "undefined" stability level.

func WithTraces

func WithTraces(createTracesReceiver CreateTracesFunc, sl component.StabilityLevel) FactoryOption

WithTraces overrides the default "error not supported" implementation for CreateTracesReceiver and the default "undefined" stability level.

type Logs

type Logs = component.LogsReceiver //nolint:staticcheck

Logs receiver receives logs. Its purpose is to translate data from any format to the collector's internal logs data format. LogsReceiver feeds a consumer.Logs with data.

For example, it could be a receiver that reads syslogs and convert them into plog.Logs.

type Metrics

type Metrics = component.MetricsReceiver //nolint:staticcheck

Metrics receiver receives metrics. Its purpose is to translate data from any format to the collector's internal metrics format. MetricsReceiver feeds a consumer.Metrics with data.

For example, it could be Prometheus data source which translates Prometheus metrics into pmetric.Metrics.

type Traces

type Traces = component.TracesReceiver //nolint:staticcheck

Traces receiver receives traces. Its purpose is to translate data from any format to the collector's internal trace format. TracesReceiver feeds a consumer.Traces with data.

For example, it could be Zipkin data source which translates Zipkin spans into ptrace.Traces.