extension

README

Extensions

Note This documentation is still in progress. For any questions, please reach out in the OpenTelemetry Gitter or refer to the issues page.

Supported service extensions (sorted alphabetically):

• Health Check
• Performance Profiler
• zPages

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: [health_check, pprof, zpages]

Health Check

Health Check extension enables an HTTP url that can be probed to check the status of the the OpenTelemetry Collector. The only configuration setting is the port in which the endpoint is going to be available, the default port is 13133.

This extension can be used as kubernetes liveness and readiness probe.

Configuration:

extensions:
  # Configures the health_check extension to expose an HTTP endpoint with the
  # service status.
  health_check:
    # Specifies the port in which the HTTP endpoint is going to be opened. The
    # default value is 13133.
    port: 13133

Performance Profiler

Performance Profiler extension enables the golang net/http/pprof endpoint. This is typically used by developers to collect performance profiles and investigate issues with the service.

Configuration:

extensions:
  # Configures the pprof (Performance Profiler) extension to expose an HTTP
  # endpoint that can be used by the golang tool pprof to collect profiles.
  # The default values are listed below.
  pprof:
    # The endpoint in which the pprof will be listening to. Use localhost:<port>
    # to make it available only locally, or ":<port>" to make it available on
    # all network interfaces.
    endpoint: localhost:1777
    # Fraction of blocking events that are profiled. A value <= 0 disables
    # profiling. See https://golang.org/pkg/runtime/#SetBlockProfileRate for details.
    block_profile_fraction: 0
    # Fraction of mutex contention events that are profiled. A value <= 0
    # disables profiling. See https://golang.org/pkg/runtime/#SetMutexProfileFraction
    # for details.
    mutex_profile_fraction: 0

zPages

Enables an extension that serves zPages, an HTTP endpoint that provides live data for debugging different components that were properly instrumented for such. All core exporters and receivers provide some zPage instrumentation.

Configuration:

extensions:
  # Configures the zPages extension to expose an HTTP endpoint that can be used
  # to debug components of the service.
  zpages:
    # Specifies the HTTP endpoint is going to be opened to serve zPages.
    # Use localhost:<port> to make it available only locally, or ":<port>" to
    # make it available on all network interfaces.
    # The default value is listed below.
    endpoint: localhost:55679

Documentation

Overview

Package extension defines service extensions that can be added to the OpenTelemetry service but that not interact if the data pipelines, but provide some functionality to the service, examples: health check endpoint, z-pages, etc.

Index

• func Build(factories ...Factory) (map[string]Factory, error)
• type Factory
• type PipelineWatcher
• type ServiceExtension

Functions

func Build

func Build(factories ...Factory) (map[string]Factory, error)

Build takes a list of extension factories and returns a map of type map[string]Factory with factory type as keys. It returns a non-nil error when more than one factories have the same type.

Types

type Factory

type Factory interface {
	// Type gets the type of the extension created by this factory.
	Type() string

	// CreateDefaultConfig creates the default configuration for the Extension.
	// This method can be called multiple times depending on the pipeline
	// configuration and should not cause side-effects that prevent the creation
	// of multiple instances of the Extension.
	// The object returned by this method needs to pass the checks implemented by
	// 'conifgcheck.ValidateConfig'. It is recommended to have such check in the
	// tests of any implementation of the Factory interface.
	CreateDefaultConfig() configmodels.Extension

	// CreateExtension creates a service extension based on the given config.
	CreateExtension(logger *zap.Logger, cfg configmodels.Extension) (ServiceExtension, error)
}

Factory is a factory interface for extensions to the service.

type PipelineWatcher

type PipelineWatcher interface {
	// Ready notifies the ServiceExtension that all pipelines were built and the
	// receivers were started, i.e.: the service is ready to receive data
	// (notice that it may already have received data when this method is called).
	Ready() error

	// NotReady notifies the ServiceExtension that all receivers are about to be stopped,
	// i.e.: pipeline receivers will not accept new data.
	// This is sent before receivers are stopped, so the ServiceExtension can take any
	// appropriate action before that happens.
	NotReady() error
}

PipelineWatcher is an extra interface for ServiceExtension hosted by the OpenTelemetry Service that is to be implemented by extensions interested in changes to pipeline states. Typically this will be used by extensions that change their behavior if data is being ingested or not, e.g.: a k8s readiness probe.

type ServiceExtension

type ServiceExtension interface {
	component.Component
}

ServiceExtension 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.