pluginreceiver

README

Plugin Receiver

The Plugin Receiver is designed to run templated OpenTelemetry pipelines. This allows users to store complex workflows within a plugin that is loaded by the receiver.

Supported pipeline types: logs, metrics, traces

Configuration

Field	Default	Required	Description
path		true	The path to the plugin file.
parameters	{ }	false	A map of key: value parameters used to render the plugin's templated pipeline.

Example Configuration

receivers:
  plugin:
    path: ./plugins/simplehost.yaml
    parameters:
      enable_cpu: false
      enable_memory: true   

Plugins

Plugins are yaml files that define three key aspects:

• Metadata
• Parameters
• Template

Example

title: Simple Host Plugin
description: A plugin utilizing the hostmetrics receiver
version: 0.0.0
parameters:
- name: enable_cpu
  type: bool
  default: false
- name: enable_memory
  type: bool
  default: true
template: |
  receivers:
    hostmetrics:
      scrapers:
  {{if .enable_cpu}}
        cpu:
  {{end}}
  {{if .enable_memory}}
        memory:
  {{end}}
  service:
    pipelines:
      metrics:
        receivers: [hostmetrics]

Metadata

Metadata fields are used to catalog and distinguish plugins. The following fields are required for a plugin:

• title
• description
• version

Parameters

Parameters are the fields used to configure a plugin. The values of these fields are used when rendering the plugin's template, resulting in a dynamic pipeline.

The following keys are used when defining a parameter.

Key	Required	Description
name	true	The name of the parameter. This is the key used when configuring the parameter within the receiver.
type	true	The data type expected for this parameter. Supported values include string, []string, int, bool, timezone.
default	false	The default value of the parameter. If not supplied during configuration, the parameter will default to this value.
required	false	Specifies if the parameter must be supplied during configuration.
supported	false	Specifies a list of supported values that can be used for this parameter.

Warning: Parameters must be defined. Undefined parameters will return an error during configuration.

Warning: Parameters must adhere to their definition. Invalid parameters will return an error during configuration.

Note: The value given for the timezone parameter type must be a standard UTC timezone, shown in this timezone list.

Template

The plugin template is a templated OpenTelemetry config. When the receiver starts, it uses the plugin's parameters and standard go templating to render an internal OpenTelemetry collector.

Warning: The supplied template must result in a valid OpenTelemetry config, with the exception of exporter components. Exporters are not supported and should be excluded from the template.

Warning: A template can only define one data type. If the template results in two different pipeline data types, such as for logs and metrics, this will result in a configuration error.

Documentation

Index

• func NewFactory() receiver.Factory
• type Config
• type Emitter
  • func (e *Emitter) Capabilities() consumer.Capabilities
  • func (e *Emitter) Shutdown(_ context.Context) error
  • func (e *Emitter) Start(_ context.Context, _ component.Host) error
• type MetricsConfig
• type Parameter
• type ParameterType
• type PipelineConfig
• type Plugin
  • func LoadPlugin(path string) (*Plugin, error)
  • func (p *Plugin) ApplyDefaults(values map[string]any) map[string]any
  • func (p *Plugin) CheckParameters(values map[string]any) error
  • func (p *Plugin) Render(values map[string]any, pluginID component.ID) (*RenderedConfig, error)
• type Receiver
  • func NewReceiver(plugin *Plugin, renderedConfig *RenderedConfig, ...) *Receiver
  • func (r *Receiver) Shutdown(ctx context.Context) error
  • func (r *Receiver) Start(ctx context.Context, host component.Host) error
• type RenderedConfig
  • func NewRenderedConfig(yamlBytes []byte) (*RenderedConfig, error)
  • func (r *RenderedConfig) GetConfigProviderSettings() (*otelcol.ConfigProviderSettings, error)
  • func (r *RenderedConfig) GetRequiredFactories(h component.Host, emitterFactory exporter.Factory) (*otelcol.Factories, error)
• type Service
• type ServiceConfig
• type TelemetryConfig

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a factory for a plugin receiver

Types

type Config

type Config struct {
	Path       string         `mapstructure:"path"`
	Parameters map[string]any `mapstructure:"parameters"`
}

Config is the configuration of a plugin receiver

type Emitter

type Emitter struct {
	consumer.Logs
	consumer.Metrics
	consumer.Traces
}

Emitter is a struct used to emit data from an internal pipeline to an external consumer. The emitter operates as a singleton exporter within an internal pipeline.

func (*Emitter) Capabilities

func (e *Emitter) Capabilities() consumer.Capabilities

Capabilities returns the capabilities of the emitter

func (*Emitter) Shutdown

func (e *Emitter) Shutdown(_ context.Context) error

Shutdown is a no-op that fulfills the component.Component interface

func (*Emitter) Start

func (e *Emitter) Start(_ context.Context, _ component.Host) error

Start is a no-op that fulfills the component.Component interface

type MetricsConfig

type MetricsConfig struct {
	Level string `yaml:"level,omitempty"`
}

MetricsConfig exposes the level of the telemetry metrics

type Parameter

type Parameter struct {
	Name        string        `yaml:"name,omitempty"`
	Type        ParameterType `yaml:"type,omitempty"`
	Default     any           `yaml:"default,omitempty"`
	Supported   []any         `yaml:"supported,omitempty"`
	Description *string       `yaml:"description,omitempty"`
	Required    bool          `yaml:"required,omitempty"`
}

Parameter is the parameter of plugin

type ParameterType

type ParameterType string

ParameterType is the type of a parameter

type PipelineConfig

type PipelineConfig struct {
	Receivers  []string `yaml:"receivers,omitempty"`
	Processors []string `yaml:"processors,omitempty"`
	Exporters  []string `yaml:"exporters,omitempty"`
}

PipelineConfig is the config of a pipeline

type Plugin

type Plugin struct {
	Title       string      `yaml:"title,omitempty"`
	Template    string      `yaml:"template,omitempty"`
	Version     string      `yaml:"version,omitempty"`
	Description string      `yaml:"description,omitempty"`
	Parameters  []Parameter `yaml:"parameters,omitempty"`
}

Plugin is a templated pipeline of receivers and processors

func LoadPlugin

func LoadPlugin(path string) (*Plugin, error)

LoadPlugin loads a plugin from a file path

func (*Plugin) ApplyDefaults

func (p *Plugin) ApplyDefaults(values map[string]any) map[string]any

ApplyDefaults returns a copy of the values map with parameter defaults applied. If a value is already present in the map, it supercedes the default.

func (*Plugin) CheckParameters

func (p *Plugin) CheckParameters(values map[string]any) error

CheckParameters checks the supplied values against the defined parameters of the plugin

func (*Plugin) Render

func (p *Plugin) Render(values map[string]any, pluginID component.ID) (*RenderedConfig, error)

Render renders the plugin's template as a config

type Receiver

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

Receiver is a receiver that runs an embedded open telemetry config as an internal service.

func NewReceiver

func NewReceiver(
	plugin *Plugin,
	renderedConfig *RenderedConfig,
	emitterFactory exporter.Factory,
	logger *zap.Logger,
) *Receiver

NewReceiver creates a new plugin receiver

func (*Receiver) Shutdown

func (r *Receiver) Shutdown(ctx context.Context) error

Shutdown stops the receiver's internal service

func (*Receiver) Start

func (r *Receiver) Start(ctx context.Context, host component.Host) error

Start starts the receiver's internal service

type RenderedConfig

type RenderedConfig struct {
	Receivers  map[string]any `yaml:"receivers,omitempty"`
	Processors map[string]any `yaml:"processors,omitempty"`
	Exporters  map[string]any `yaml:"exporters,omitempty"`
	Extensions map[string]any `yaml:"extensions,omitempty"`
	Service    ServiceConfig  `yaml:"service,omitempty"`
}

RenderedConfig is the rendered config of a plugin

func NewRenderedConfig

func NewRenderedConfig(yamlBytes []byte) (*RenderedConfig, error)

NewRenderedConfig creates a RenderedConfig with statically overwritten Exporters info

func (*RenderedConfig) GetConfigProviderSettings

func (r *RenderedConfig) GetConfigProviderSettings() (*otelcol.ConfigProviderSettings, error)

GetConfigProviderSettings returns config provider settings for the rendered config

func (*RenderedConfig) GetRequiredFactories

func (r *RenderedConfig) GetRequiredFactories(h component.Host, emitterFactory exporter.Factory) (*otelcol.Factories, error)

GetRequiredFactories finds and returns the factories required for the rendered config

type Service

type Service interface {
	Run(ctx context.Context) error
	Shutdown()
	GetState() otelcol.State
}

Service is an interface for running an internal open telemetry service

type ServiceConfig

type ServiceConfig struct {
	Extensions []string                  `yaml:"extensions,omitempty"`
	Pipelines  map[string]PipelineConfig `yaml:"pipelines,omitempty"`
	Telemetry  TelemetryConfig           `yaml:"telemetry,omitempty"`
}

ServiceConfig is the config of a collector service

type TelemetryConfig

type TelemetryConfig struct {
	Metrics MetricsConfig `yaml:"metrics,omitempty"`
}

TelemetryConfig is a representation of collector telemetry settings