service

README

OpenTelemetry Collector Service

How to provide configuration?

The --config flag accepts either a file path or values in the form of a config URI "<scheme>:<opaque_data>". Currently, the OpenTelemetry Collector supports the following providers scheme:

• file - Reads configuration from a file. E.g. file:path/to/config.yaml.
• env - Reads configuration from an environment variable. E.g. env:MY_CONFIG_IN_AN_ENVVAR.
• yaml - Reads configuration from yaml bytes. E.g. yaml:exporters::logging::loglevel: debug.
• http - Reads configuration from a HTTP URI. E.g. http://www.example.com

For more technical details about how configuration is resolved you can read the configuration resolving design.

Single Config Source

1. Simple local file:

   ./otelcorecol --config=examples/local/otel-config.yaml

2. Simple local file using the new URI format:

   ./otelcorecol --config=file:examples/local/otel-config.yaml

3. Config provided via an environment variable:

   ./otelcorecol --config=env:MY_CONFIG_IN_AN_ENVVAR

Multiple Config Sources

1. Merge a otel-config.yaml file with the content of an environment variable MY_OTHER_CONFIG and use the merged result as the config:

   ./otelcorecol --config=file:examples/local/otel-config.yaml --config=env:MY_OTHER_CONFIG

2. Merge a config.yaml file with the content of a yaml bytes configuration (overwrites the exporters::logging::loglevel config) and use the content as the config:

   ./otelcorecol --config=file:examples/local/otel-config.yaml --config="yaml:exporters::logging::loglevel: info"

How to check components available in a distribution

Use the sub command build-info. Below is an example:

   ./otelcorecol build-info

Sample output:

buildinfo:
   command: otelcorecol
   description: Local OpenTelemetry Collector binary, testing only.
   version: 0.62.1-dev
receivers:
   - otlp
processors:
   - memory_limiter
   - batch
exporters:
   - otlp
   - otlphttp
   - logging
extensions:
   - zpages
   - memory_ballast

How to override config properties?

The --set flag allows to set arbitrary config property. The --set values are merged into the final configuration after all the sources specified by the --config are resolved and merged.

The Format and Limitations of --set

Simple property

The --set option takes always one key/value pair, and it is used like this: --set key=value. The YAML equivalent of that is:

key: value

Complex nested keys

Use dot (.) in the pair's name as key separator to reference nested map values. For example, --set outer.inner=value is translated into this:

outer:
  inner: value

Multiple values

To set multiple values specify multiple --set flags, so --set a=b --set c=d becomes:

a: b
c: d

Array values

Arrays can be expressed by enclosing values in []. For example, --set "key=[a, b, c]" translates to:

key:
  - a
  - b
  - c

Map values

Maps can be expressed by enclosing values in {}. For example, "--set "key={a: c}" translates to:

key:
  a: c

Limitations

1. Does not support setting a key that contains a dot ..
2. Does not support setting a key that contains a equal sign =.
3. The configuration key separator inside the value part of the property is "::". For example --set "name={a::b: c}" is equivalent with --set name.a.b=c.

Documentation

Overview

Package service handles the command-line, configuration, and runs the OpenTelemetry Collector.

Index

• func NewCommand(set CollectorSettings) *cobra.Command
• type Collector
  • func New(set CollectorSettings) (*Collector, error)
  • func (col *Collector) GetState() State
  • func (col *Collector) Run(ctx context.Context) error
  • func (col *Collector) Shutdown()
• type CollectorSettings
• type Config
  • func (cfg *Config) Validate() error
• type ConfigProvider
  • func NewConfigProvider(set ConfigProviderSettings) (ConfigProvider, error)
• type ConfigProviderSettings
• type ConfigService
  • func (cfg *ConfigService) Validate() error
• type ConfigServicePipeline
  • func (cfg *ConfigServicePipeline) Validate() error
• type State
  • func (s State) String() string

Functions

func NewCommand

func NewCommand(set CollectorSettings) *cobra.Command

NewCommand constructs a new cobra.Command using the given CollectorSettings.

Types

type Collector

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

Collector represents a server providing the OpenTelemetry Collector service. Deprecated: [v0.67.0] use otelcol.Collector

func New

func New(set CollectorSettings) (*Collector, error)

New creates and returns a new instance of Collector. Deprecated: [v0.67.0] use otelcol.NewCollector

func (*Collector) GetState

func (col *Collector) GetState() State

GetState returns current state of the collector server.

func (*Collector) Run

func (col *Collector) Run(ctx context.Context) error

Run starts the collector according to the given configuration, and waits for it to complete. Consecutive calls to Run are not allowed, Run shouldn't be called once a collector is shut down.

func (*Collector) Shutdown

func (col *Collector) Shutdown()

Shutdown shuts down the collector server.

type CollectorSettings

type CollectorSettings struct {
	// Factories component factories.
	Factories component.Factories

	// BuildInfo provides collector start information.
	BuildInfo component.BuildInfo

	// DisableGracefulShutdown disables the automatic graceful shutdown
	// of the collector on SIGINT or SIGTERM.
	// Users who want to handle signals themselves can disable this behavior
	// and manually handle the signals to shutdown the collector.
	DisableGracefulShutdown bool

	// ConfigProvider provides the service configuration.
	// If the provider watches for configuration change, collector may reload the new configuration upon changes.
	ConfigProvider ConfigProvider

	// LoggingOptions provides a way to change behavior of zap logging.
	LoggingOptions []zap.Option

	// SkipSettingGRPCLogger avoids setting the grpc logger
	SkipSettingGRPCLogger bool
	// contains filtered or unexported fields
}

CollectorSettings holds configuration for creating a new Collector. Deprecated: [v0.66.0] use otelcol.CollectorSettings.

type Config

type Config struct {
	// Receivers is a map of ComponentID to Receivers.
	Receivers map[component.ID]component.Config

	// Exporters is a map of ComponentID to Exporters.
	Exporters map[component.ID]component.Config

	// Processors is a map of ComponentID to Processors.
	Processors map[component.ID]component.Config

	// Extensions is a map of ComponentID to extensions.
	Extensions map[component.ID]component.Config

	Service ConfigService
}

Deprecated: [v0.67.0] use otelcol.Config

func (*Config) Validate

func (cfg *Config) Validate() error

Validate returns an error if the config is invalid.

This function performs basic validation of configuration. There may be more subtle invalid cases that we currently don't check for but which we may want to add in the future (e.g. disallowing receiving and exporting on the same endpoint).

type ConfigProvider

type ConfigProvider interface {
	// Get returns the service configuration, or error otherwise.
	//
	// Should never be called concurrently with itself, Watch or Shutdown.
	Get(ctx context.Context, factories component.Factories) (*Config, error)

	// Watch blocks until any configuration change was detected or an unrecoverable error
	// happened during monitoring the configuration changes.
	//
	// Error is nil if the configuration is changed and needs to be re-fetched. Any non-nil
	// error indicates that there was a problem with watching the config changes.
	//
	// Should never be called concurrently with itself or Get.
	Watch() <-chan error

	// Shutdown signals that the provider is no longer in use and the that should close
	// and release any resources that it may have created.
	//
	// This function must terminate the Watch channel.
	//
	// Should never be called concurrently with itself or Get.
	Shutdown(ctx context.Context) error
}

ConfigProvider provides the service configuration.

The typical usage is the following:

cfgProvider.Get(...)
cfgProvider.Watch() // wait for an event.
cfgProvider.Get(...)
cfgProvider.Watch() // wait for an event.
// repeat Get/Watch cycle until it is time to shut down the Collector process.
cfgProvider.Shutdown()

Deprecated: [v0.67.0] use otelcol.ConfigProvider

func NewConfigProvider

func NewConfigProvider(set ConfigProviderSettings) (ConfigProvider, error)

NewConfigProvider returns a new ConfigProvider that provides the service configuration: * Initially it resolves the "configuration map":

• Retrieve the confmap.Conf by merging all retrieved maps from the given `locations` in order.
• Then applies all the confmap.Converter in the given order.

* Then unmarshalls the confmap.Conf into the service Config. Deprecated: [v0.67.0] use otelcol.NewConfigProvider

type ConfigProviderSettings

type ConfigProviderSettings struct {
	// ResolverSettings are the settings to configure the behavior of the confmap.Resolver.
	ResolverSettings confmap.ResolverSettings
}

ConfigProviderSettings are the settings to configure the behavior of the ConfigProvider. Deprecated: [v0.67.0] use otelcol.ConfigProviderSettings

type ConfigService

type ConfigService struct {
	// Telemetry is the configuration for collector's own telemetry.
	Telemetry telemetry.Config `mapstructure:"telemetry"`

	// Extensions are the ordered list of extensions configured for the service.
	Extensions []component.ID `mapstructure:"extensions"`

	// Pipelines are the set of data pipelines configured for the service.
	Pipelines map[component.ID]*ConfigServicePipeline `mapstructure:"pipelines"`
}

ConfigService defines the configurable components of the service.

func (*ConfigService) Validate

func (cfg *ConfigService) Validate() error

type ConfigServicePipeline

type ConfigServicePipeline struct {
	Receivers  []component.ID `mapstructure:"receivers"`
	Processors []component.ID `mapstructure:"processors"`
	Exporters  []component.ID `mapstructure:"exporters"`
}

func (*ConfigServicePipeline) Validate

func (cfg *ConfigServicePipeline) Validate() error

type State

type State int

State defines Collector's state. Deprecated: [v0.67.0] use otelcol.State

const (
	// Deprecated: [v0.67.0] use otelcol.StateStarting
	StateStarting State = iota
	// Deprecated: [v0.67.0] use otelcol.StateRunning
	StateRunning
	// Deprecated: [v0.67.0] use otelcol.StateClosing
	StateClosing
	// Deprecated: [v0.67.0] use otelcol.StateClosed
	StateClosed
)

func (State) String

func (s State) String() string