Documentation

Index

Constants

View Source
const DefaultPeriod = 10 * time.Second

    DefaultPeriod is used for:

    - the minimum time between calls to Collect() - the timeout for Export() - the timeout for Collect().

    Variables

    View Source
    var ErrControllerStarted = fmt.Errorf("controller already started")

      ErrControllerStarted indicates that a controller was started more than once.

      Functions

      This section is empty.

      Types

      type Config

      type Config struct {
      	// Resource is the OpenTelemetry resource associated with all Meters
      	// created by the Controller.
      	Resource *resource.Resource
      
      	// CollectPeriod is the interval between calls to Collect a
      	// checkpoint.
      	//
      	// When pulling metrics and not exporting, this is the minimum
      	// time between calls to Collect.  In a pull-only
      	// configuration, collection is performed on demand; set
      	// CollectPeriod to 0 always recompute the export record set.
      	//
      	// When exporting metrics, this must be > 0.
      	//
      	// Default value is 10s.
      	CollectPeriod time.Duration
      
      	// CollectTimeout is the timeout of the Context passed to
      	// Collect() and subsequently to Observer instrument callbacks.
      	//
      	// Default value is 10s.  If zero, no Collect timeout is applied.
      	CollectTimeout time.Duration
      
      	// Exporter is used for exporting metric data.
      	//
      	// Note: Exporters such as Prometheus that pull data do not implement
      	// export.Exporter.  These will directly call Collect() and ForEach().
      	Exporter export.Exporter
      
      	// PushTimeout is the timeout of the Context when a exporter is configured.
      	//
      	// Default value is 10s.  If zero, no Export timeout is applied.
      	PushTimeout time.Duration
      }

        Config contains configuration for a basic Controller.

        type Controller

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

          Controller organizes and synchronizes collection of metric data in both "pull" and "push" configurations. This supports two distinct modes:

          - Push and Pull: Start() must be called to begin calling the exporter;

          Collect() is called periodically by a background thread after starting
          the controller.
          

          - Pull-Only: Start() is optional in this case, to call Collect periodically.

          If Start() is not called, Collect() can be called manually to initiate
          collection
          

          The controller supports mixing push and pull access to metric data using the export.CheckpointSet RWLock interface. Collection will be blocked by a pull request in the basic controller.

          func New

          func New(checkpointer export.Checkpointer, opts ...Option) *Controller

            New constructs a Controller using the provided checkpointer and options (including optional exporter) to configure a metric export pipeline.

            func (*Controller) Collect

            func (c *Controller) Collect(ctx context.Context) error

              Collect requests a collection. The collection will be skipped if the last collection is aged less than the configured collection period.

              func (*Controller) ForEach

              func (c *Controller) ForEach(ks export.ExportKindSelector, f func(export.Record) error) error

                Foreach gives the caller read-locked access to the current export.CheckpointSet.

                func (*Controller) IsRunning

                func (c *Controller) IsRunning() bool

                  IsRunning returns true if the controller was started via Start(), indicating that the current export.CheckpointSet is being kept up-to-date.

                  func (*Controller) MeterProvider

                  func (c *Controller) MeterProvider() metric.MeterProvider

                    MeterProvider returns a MeterProvider instance for this controller.

                    func (*Controller) SetClock

                    func (c *Controller) SetClock(clock controllerTime.Clock)

                      SetClock supports setting a mock clock for testing. This must be called before Start().

                      func (*Controller) Start

                      func (c *Controller) Start(ctx context.Context) error

                        Start begins a ticker that periodically collects and exports metrics with the configured interval. This is required for calling a configured Exporter (see WithExporter) and is otherwise optional when only pulling metric data.

                        The passed context is passed to Collect() and subsequently to asynchronous instrument callbacks. Returns an error when the controller was already started.

                        Note that it is not necessary to Start a controller when only pulling data; use the Collect() and ForEach() methods directly in this case.

                        func (*Controller) Stop

                        func (c *Controller) Stop(ctx context.Context) error

                          Stop waits for the background goroutine to return and then collects and exports metrics one last time before returning. The passed context is passed to the final Collect() and subsequently to the final asynchronous instruments.

                          Note that Stop() will not cancel an ongoing collection or export.

                          type Option

                          type Option interface {
                          	// Apply sets the Option value of a Config.
                          	Apply(*Config)
                          }

                            Option is the interface that applies the value to a configuration option.

                            func WithCollectPeriod

                            func WithCollectPeriod(period time.Duration) Option

                              WithCollectPeriod sets the CollectPeriod configuration option of a Config.

                              func WithCollectTimeout

                              func WithCollectTimeout(timeout time.Duration) Option

                                WithCollectTimeout sets the CollectTimeout configuration option of a Config.

                                func WithExporter

                                func WithExporter(exporter export.Exporter) Option

                                  WithExporter sets the exporter configuration option of a Config.

                                  func WithPushTimeout

                                  func WithPushTimeout(timeout time.Duration) Option

                                    WithPushTimeout sets the PushTimeout configuration option of a Config.

                                    func WithResource

                                    func WithResource(r *resource.Resource) Option

                                      WithResource sets the Resource configuration option of a Config.