simple

Documentation

Overview

Package simple facilitates building pdata.Metrics in receivers in an easier and more fluent way than using pdata.Metrics directly.

Index

• type Metrics
  • func (mb *Metrics) AddDGaugeDataPoint(name string, metricValue float64) *Metrics
  • func (mb *Metrics) AddDHistogramRawDataPoint(name string, hist pdata.HistogramDataPoint) *Metrics
  • func (mb *Metrics) AddDSumDataPoint(name string, metricValue float64) *Metrics
  • func (mb *Metrics) AddGaugeDataPoint(name string, metricValue int64) *Metrics
  • func (mb *Metrics) AddHistogramRawDataPoint(name string, hist pdata.IntHistogramDataPoint) *Metrics
  • func (mb *Metrics) AddSumDataPoint(name string, metricValue int64) *Metrics
  • func (mb Metrics) AsSafe() *SafeMetrics
  • func (mb *Metrics) WithLabels(l map[string]string) *Metrics
• type SafeMetrics
  • func (mb *SafeMetrics) AddDGaugeDataPoint(name string, metricValue float64) *SafeMetrics
  • func (mb *SafeMetrics) AddDHistogramRawDataPoint(name string, hist pdata.HistogramDataPoint) *SafeMetrics
  • func (mb *SafeMetrics) AddDSumDataPoint(name string, metricValue float64) *SafeMetrics
  • func (mb *SafeMetrics) AddGaugeDataPoint(name string, metricValue int64) *SafeMetrics
  • func (mb *SafeMetrics) AddHistogramRawDataPoint(name string, hist pdata.IntHistogramDataPoint) *SafeMetrics
  • func (mb *SafeMetrics) AddSumDataPoint(name string, metricValue int64) *SafeMetrics
  • func (mb *SafeMetrics) WithLabels(l map[string]string) *SafeMetrics

Examples

• Metrics
• SafeMetrics

Types

type Metrics

type Metrics struct {
	// REQUIRED. A Metrics object that has been created with
	// `pdata.NewMetrics()`.  This is required to be set on the builder.  All
	// metrics added will go into this immediately upon invocation of Add*
	// methods.  Do not change this once initially set.
	pdata.Metrics

	// MetricFactoriesByName is an optional map of metric factories that will
	// be created with the appropriate name, description, and type field.  This
	// is intended to be used with the metadata code generation modules but can
	// be used apart from that just as well.  The returned metrics are expected
	// to be initialized.
	MetricFactoriesByName map[string]func(pdata.Metric)

	// If set, this instrumentation library name will be used for all metrics
	// generated by this builder.  This is meant to be set once at builder
	// creation and not changed later.
	InstrumentationLibraryName string
	// If set, this instrumentation library version will be used for all
	// metrics generated by this builder.  This is meant to be set once at
	// builder creation and not changed later.
	InstrumentationLibraryVersion string
	// These attributes will be added to the Resource object on all
	// ResourceMetrics instances created by the builder.  This is meant to be
	// set once at builder creation and not changed later.
	ResourceAttributes map[string]string
	// This time will be used as the Timestamp for all metrics generated.  It
	// can be updated with a new timestamp at any time.
	Timestamp time.Time
	// A set of labels that will be applied to all datapoints emitted by the
	// builder.
	Labels map[string]string
	// contains filtered or unexported fields
}

Metrics facilitates building pdata.Metrics in receivers. It is meant to be much easier and more fluent than than using pdata.Metrics directly. All of the exported methods on it return the same instance of Metrics as a return value, allowing you to chain method calls easily, similar to the Java builder pattern.

All of the public fields in this structure are meant to be set before the first data point is added, and should not be changed afterwards.

The Metrics is designed for cases where receivers are generating metrics from scratch, where generally you will have a single datapoint per metric/label combination.

One restriction this helper imposes is that a particular metric name must only be used with a single data type for all instances derived from a base helper, including the base instance. This restriction greatly simplifies the logic to reuse metrics for multiple datapoints and it is generally easier for backends to not have to deal with conflicting types anyway.

It is NOT thread-safe, so you should use an external mutex if using it from multiple goroutines.

Example

metrics := pdata.NewMetrics()

mb := Metrics{
	Metrics:                       metrics,
	InstrumentationLibraryName:    "example",
	InstrumentationLibraryVersion: "0.1",
	ResourceAttributes: map[string]string{
		"host": "my-host",
	},
	Timestamp: time.Now(),
}

for _, disk := range []string{"sda", "sdb", "sdc"} {
	// All metrics added after this will have these labels
	diskBuilder := mb.WithLabels(map[string]string{
		"disk": disk,
	}).AddGaugeDataPoint("disk.usage", 9000000)

	// Add metrics in a chained manner
	diskBuilder.
		AddGaugeDataPoint("disk.capacity", 9000000).
		AddDGaugeDataPoint("disk.temp", 30.5)

	// Add additional labels
	diskBuilder.WithLabels(map[string]string{
		"direction": "read",
	}).AddSumDataPoint("disk.ops", 50)

	diskBuilder.WithLabels(map[string]string{
		"direction": "write",
	}).AddSumDataPoint("disk.ops", 80)
}

metricCount, dpCount := metrics.MetricAndDataPointCount()
fmt.Printf("Metrics: %d\nDataPoints: %d", metricCount, dpCount)

// Do not reuse Metrics once you are done using the generated Metrics. Make
// a new instance of it along with a new instance of pdata.Metrics.

Output:

Metrics: 4
DataPoints: 15

func (*Metrics) AddDGaugeDataPoint

func (mb *Metrics) AddDGaugeDataPoint(name string, metricValue float64) *Metrics

AddDGaugeDataPoint adds a double gauge data point.

func (*Metrics) AddDHistogramRawDataPoint

func (mb *Metrics) AddDHistogramRawDataPoint(name string, hist pdata.HistogramDataPoint) *Metrics

AddDHistogramRawDataPoint adds a double histogram data point.

func (*Metrics) AddDSumDataPoint

func (mb *Metrics) AddDSumDataPoint(name string, metricValue float64) *Metrics

AddDSumDataPoint adds a double sum data point.

func (*Metrics) AddGaugeDataPoint

func (mb *Metrics) AddGaugeDataPoint(name string, metricValue int64) *Metrics

AddGaugeDataPoint adds an integer gauge data point.

func (*Metrics) AddHistogramRawDataPoint

func (mb *Metrics) AddHistogramRawDataPoint(name string, hist pdata.IntHistogramDataPoint) *Metrics

AddHistogramRawDataPoint adds an integer histogram data point.

func (*Metrics) AddSumDataPoint

func (mb *Metrics) AddSumDataPoint(name string, metricValue int64) *Metrics

AddSumDataPoint adds an integer sum data point.

func (Metrics) AsSafe

func (mb Metrics) AsSafe() *SafeMetrics

AsSafe returns an instance of this builder wrapped in SafeMetrics that ensures all of the public methods on this instance will be thread-safe between goroutines. You must explicitly type these instances as SafeMetrics.

func (*Metrics) WithLabels

func (mb *Metrics) WithLabels(l map[string]string) *Metrics

WithLabels returns a new, independent builder with additional labels. These labels will be combined with the Labels that can be set on the struct. All subsequent calls to create metrics will create metrics that use these labels. The input map's entries are copied so the map can be mutated freely by the caller afterwards without affecting the builder.

type SafeMetrics

type SafeMetrics struct {
	*sync.Mutex
	*Metrics
}

SafeMetrics is a wrapper for Metrics that ensures the wrapped instance can be used safely across goroutines. It is meant to be created from the AsSafe on Metrics.

Example

metrics := pdata.NewMetrics()

mb := Metrics{
	Metrics:                       metrics,
	InstrumentationLibraryName:    "example",
	InstrumentationLibraryVersion: "0.1",
	ResourceAttributes: map[string]string{
		"host": "my-host",
	},
	Timestamp: time.Now(),
}.AsSafe()

var wg sync.WaitGroup
for _, disk := range []string{"sda", "sdb", "sdc"} {
	wg.Add(1)
	go func(disk string) {
		// All metrics added after this will have these labels
		diskBuilder := mb.WithLabels(map[string]string{
			"disk": disk,
		}).AddGaugeDataPoint("disk.usage", 9000000)

		// Add metrics in a chained manner
		diskBuilder.
			AddGaugeDataPoint("disk.capacity", 9000000).
			AddSumDataPoint("disk.reads", 50)

		// Or add them on their own
		diskBuilder.AddDGaugeDataPoint("disk.temp", 30.5)

		wg.Done()
	}(disk)
}
wg.Wait()

metricCount, dpCount := metrics.MetricAndDataPointCount()
fmt.Printf("Metrics: %d\nDataPoints: %d", metricCount, dpCount)

Output:

Metrics: 4
DataPoints: 12

func (*SafeMetrics) AddDGaugeDataPoint

func (mb *SafeMetrics) AddDGaugeDataPoint(name string, metricValue float64) *SafeMetrics

AddDGaugeDataPoint wraps Metrics.AddDGaugeDataPoint.

func (*SafeMetrics) AddDHistogramRawDataPoint

func (mb *SafeMetrics) AddDHistogramRawDataPoint(name string, hist pdata.HistogramDataPoint) *SafeMetrics

AddDHistogramRawDataPoint wraps AddDHistogramRawDataPoint.

func (*SafeMetrics) AddDSumDataPoint

func (mb *SafeMetrics) AddDSumDataPoint(name string, metricValue float64) *SafeMetrics

AddDSumDataPoint wraps Metrics.AddDSumDataPoint.

func (*SafeMetrics) AddGaugeDataPoint

func (mb *SafeMetrics) AddGaugeDataPoint(name string, metricValue int64) *SafeMetrics

AddGaugeDataPoint wraps Metrics.AddGaugeDataPoint.

func (*SafeMetrics) AddHistogramRawDataPoint

func (mb *SafeMetrics) AddHistogramRawDataPoint(name string, hist pdata.IntHistogramDataPoint) *SafeMetrics

AddHistogramRawDataPoint wraps Metrics.AddHistogramRawDataPoint.

func (*SafeMetrics) AddSumDataPoint

func (mb *SafeMetrics) AddSumDataPoint(name string, metricValue int64) *SafeMetrics

AddSumDataPoint wraps Metrics.AddSumDataPoint.

func (*SafeMetrics) WithLabels

func (mb *SafeMetrics) WithLabels(l map[string]string) *SafeMetrics

WithLabels wraps Metrics.WithLabels.