componentstatus

Documentation

Overview

Package componentstatus is an experimental module that defines how components should report health statues, how collector hosts should facilitate component status reporting, and how extensions should watch for new component statuses.

This package is currently under development and is exempt from the Collector SIG's breaking change policy.

Index

• func ReportStatus(host component.Host, e *Event)
• func StatusIsError(status Status) bool
• type Event
  • func NewEvent(status Status) *Event
  • func NewFatalErrorEvent(err error) *Event
  • func NewPermanentErrorEvent(err error) *Event
  • func NewRecoverableErrorEvent(err error) *Event
  • func (ev *Event) Err() error
  • func (ev *Event) Status() Status
  • func (ev *Event) Timestamp() time.Time
• type InstanceID
  • func NewInstanceID(componentID component.ID, kind component.Kind, pipelineIDs ...pipeline.ID) *InstanceID
  • func (id *InstanceID) AllPipelineIDs(f func(pipeline.ID) bool)
  • func (id *InstanceID) ComponentID() component.ID
  • func (id *InstanceID) Kind() component.Kind
  • func (id *InstanceID) WithPipelines(pipelineIDs ...pipeline.ID) *InstanceID
• type Reporter
• type Status
  • func (s Status) String() string
• type Watcher

Functions

func ReportStatus

func ReportStatus(host component.Host, e *Event)

ReportStatus is a helper function that handles checking if the component.Host has implemented Reporter. If it has, the Event is reported. Otherwise, nothing happens.

func StatusIsError

func StatusIsError(status Status) bool

StatusIsError returns true for error statuses (e.g. StatusRecoverableError, StatusPermanentError, or StatusFatalError)

Types

type Event

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

Event contains a status and timestamp, and can contain an error

func NewEvent

func NewEvent(status Status) *Event

NewEvent creates and returns a Event with the specified status and sets the timestamp time.Now(). To set an error on the event for an error status use one of the dedicated constructors (e.g. NewRecoverableErrorEvent, NewPermanentErrorEvent, NewFatalErrorEvent)

func NewFatalErrorEvent

func NewFatalErrorEvent(err error) *Event

NewFatalErrorEvent wraps the fatal runtime error passed as argument as a Event with a status StatusFatalError and a timestamp set to time.Now().

func NewPermanentErrorEvent

func NewPermanentErrorEvent(err error) *Event

NewPermanentErrorEvent wraps an error requiring human intervention to fix passed as argument as a Event with a status StatusPermanentError and a timestamp set to time.Now().

func NewRecoverableErrorEvent

func NewRecoverableErrorEvent(err error) *Event

NewRecoverableErrorEvent wraps a transient error passed as argument as a Event with a status StatusRecoverableError and a timestamp set to time.Now().

func (*Event) Err

func (ev *Event) Err() error

Err returns the error associated with the Event.

func (*Event) Status

func (ev *Event) Status() Status

Status returns the Status (enum) associated with the Event

func (*Event) Timestamp

func (ev *Event) Timestamp() time.Time

Timestamp returns the timestamp associated with the Event

type InstanceID

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

InstanceID uniquely identifies a component instance

TODO: consider moving this struct to a new package/module like `extension/statuswatcher` https://github.com/open-telemetry/opentelemetry-collector/issues/10764

func NewInstanceID

func NewInstanceID(componentID component.ID, kind component.Kind, pipelineIDs ...pipeline.ID) *InstanceID

NewInstanceID returns an ID that uniquely identifies a component.

func (*InstanceID) AllPipelineIDs

func (id *InstanceID) AllPipelineIDs(f func(pipeline.ID) bool)

AllPipelineIDs calls f for each pipeline this instance is associated with. If f returns false it will stop iteration.

func (*InstanceID) ComponentID

func (id *InstanceID) ComponentID() component.ID

ComponentID returns the ComponentID associated with this instance.

func (*InstanceID) Kind

func (id *InstanceID) Kind() component.Kind

Kind returns the component Kind associated with this instance.

func (*InstanceID) WithPipelines

func (id *InstanceID) WithPipelines(pipelineIDs ...pipeline.ID) *InstanceID

WithPipelines returns a new InstanceID updated to include the given pipelineIDs.

type Reporter

type Reporter interface {
	// Report allows a component to report runtime changes in status. The service
	// will automatically report status for a component during startup and shutdown. Components can
	// use this method to report status after start and before shutdown. For more details about
	// component status reporting see: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-status.md
	Report(*Event)
}

Reporter is an extra interface for `component.Host` implementations. A Reporter defines how to report a `componentstatus.Event`.

type Status

type Status int32

const (
	// StatusNone indicates absence of component status.
	StatusNone Status = iota
	// StatusStarting indicates the component is starting.
	StatusStarting
	// StatusOK indicates the component is running without issues.
	StatusOK
	// StatusRecoverableError indicates that the component has experienced a transient error and may recover.
	StatusRecoverableError
	// StatusPermanentError indicates that the component has detected a condition at runtime that will need human intervention to fix. The collector will continue to run in a degraded mode.
	StatusPermanentError
	// StatusFatalError indicates that the collector has experienced a fatal runtime error and will shut down.
	StatusFatalError
	// StatusStopping indicates that the component is in the process of shutting down.
	StatusStopping
	// StatusStopped indicates that the component has completed shutdown.
	StatusStopped
)

Enumeration of possible component statuses

func (Status) String

func (s Status) String() string

String returns a string representation of a Status

type Watcher

type Watcher interface {
	// ComponentStatusChanged notifies about a change in the source component status.
	// Extensions that implement this interface must be ready that the ComponentStatusChanged
	// may be called before, after or concurrently with calls to Component.Start() and Component.Shutdown().
	// The function may be called concurrently with itself.
	ComponentStatusChanged(source *InstanceID, event *Event)
}

Watcher is an extra interface for Extension hosted by the OpenTelemetry Collector that is to be implemented by extensions interested in changes to component status.

TODO: consider moving this interface to a new package/module like `extension/statuswatcher` https://github.com/open-telemetry/opentelemetry-collector/issues/10764