extension

README

General Information

Extensions provide capabilities on top of the primary functionality of the collector. Generally, extensions are used for implementing components that can be added to the Collector, but which do not require direct access to telemetry data and are not part of the pipelines (like receivers, processors or exporters). Example extensions are: Memory Limiter extension that prevents out of memory situations or zPages extension that provides live data for debugging different components.

Supported service extensions (sorted alphabetically):

• Memory Limiter
• zPages

The contributors repository may have more extensions that can be added to custom builds of the Collector.

Ordering Extensions

The order extensions are specified for the service is important as this is the order in which each extension will be started and the reverse order in which they will be shutdown. The ordering is determined in the extensions tag under the service tag in the configuration file, example:

service:
  # Extensions specified below are going to be loaded by the service in the
  # order given below, and shutdown on reverse order.
  extensions: [extension1, extension2]

Documentation

Overview

Example

Example demonstrates how a Factory creates an extension using Settings.ID.

package main

import (
	"context"
	"fmt"

	"go.opentelemetry.io/collector/component"
	"go.opentelemetry.io/collector/extension"
)

// exampleExtension is a minimal extension that reports its lifecycle.
type exampleExtension struct {
	id component.ID
}

// Start is called by the Collector when the extension is started.
func (e *exampleExtension) Start(_ context.Context, _ component.Host) error {
	fmt.Printf("extension %q started\n", e.id)
	return nil
}

// Shutdown is called by the Collector when the extension is stopped.
func (e *exampleExtension) Shutdown(_ context.Context) error {
	fmt.Printf("extension %q stopped\n", e.id)
	return nil
}

func createExampleConfig() component.Config {
	return struct{}{}
}

func createExampleExtension(_ context.Context, set extension.Settings, _ component.Config) (extension.Extension, error) {
	return &exampleExtension{id: set.ID}, nil
}

// Example demonstrates how a Factory creates an extension using Settings.ID.
func main() {
	extType := component.MustNewType("example")

	factory := extension.NewFactory(
		extType,
		createExampleConfig,
		createExampleExtension,
		component.StabilityLevelDevelopment,
	)

	settings := extension.Settings{
		ID: component.NewID(extType),
	}

	ext, err := factory.Create(context.Background(), settings, factory.CreateDefaultConfig())
	if err != nil {
		panic(err)
	}

	_ = ext.Start(context.Background(), nil)
	_ = ext.Shutdown(context.Background())

}

Output:
extension "example" started
extension "example" stopped

Index

• type CreateFunc
• type Extension
• type Factory
  • func NewFactory(cfgType component.Type, createDefaultConfig component.CreateDefaultConfigFunc, ...) Factory
• type Settings

Examples

• Package

Types

type CreateFunc

type CreateFunc func(context.Context, Settings, component.Config) (Extension, error)

CreateFunc is the equivalent of Factory.Create(...) function.

type Extension

type Extension interface {
	component.Component
}

Extension is the interface for objects hosted by the OpenTelemetry Collector that don't participate directly on data pipelines but provide some functionality to the service, examples: health check endpoint, z-pages, etc.

type Factory

type Factory interface {
	component.Factory

	// Create an extension based on the given config.
	Create(ctx context.Context, set Settings, cfg component.Config) (Extension, error)

	// Stability gets the stability level of the Extension.
	Stability() component.StabilityLevel
	// contains filtered or unexported methods
}

func NewFactory

func NewFactory(
	cfgType component.Type,
	createDefaultConfig component.CreateDefaultConfigFunc,
	createServiceExtension CreateFunc,
	sl component.StabilityLevel,
) Factory

NewFactory returns a new Factory based on this configuration.

type Settings

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
	// contains filtered or unexported fields
}

Settings is passed to Factory.Create(...) function.