metrics

Documentation

Index

• Constants
• type CWEmbeddedMetricsManager
  • func NewCWEmbeddedMetrics(writer io.Writer) *CWEmbeddedMetricsManager
  • func (c *CWEmbeddedMetricsManager) NewCounter(name, unit string) Counter
  • func (c *CWEmbeddedMetricsManager) Run(ctx context.Context, interval time.Duration)
  • func (c *CWEmbeddedMetricsManager) Sync() error
• type Counter
• type Dimension
• type DimensionSet
• type DimensionValues
  • func (lvs DimensionValues) With(dvs ...string) DimensionValues
• type DimensionsCounter
  • func (d *DimensionsCounter) Add(delta float64)
  • func (d *DimensionsCounter) With(dvs ...string) Counter
• type EmbeddedMetric
• type Logger
  • func MustLogger(dimensionSets []DimensionSet) Logger
  • func NewLogger(dimensionSets []DimensionSet) (Logger, error)
• type Manager
• type Metric
• type MetricDirectiveObject
• type Space
  • func NewSpace() *Space
  • func (s *Space) Observe(name, unit string, dvs DimensionValues, value float64)
  • func (s *Space) Reset() *Space
  • func (s *Space) Walk(fn func(name, unit string, dvs DimensionValues, sum float64, count int64) bool)
• type StaticLogger
  • func MustStaticLogger(dimensionSets []DimensionSet, metrics []Metric) *StaticLogger
  • func NewStaticLogger(dimensionSets []DimensionSet, metrics []Metric) (*StaticLogger, error)
  • func (l *StaticLogger) Log(metrics []Metric, dimensions ...Dimension)
  • func (l *StaticLogger) LogSingle(value interface{}, dimensions ...Dimension)

Constants

const (
	SubsystemDimension = "Subsystem"

	StatusDimension = "Status"

	SourceIDDimension = "ID"

	LogTypeDimension = "LogType"
)

const (
	UnitBytes   = "Bytes"
	UnitSeconds = "Seconds"
	// UnitMicroseconds = "Microseconds"
	UnitMilliseconds = "Milliseconds"
	UnitCount        = "Count"
)

Values that AWS understands as Metric Units

const (
	Namespace = "Panther"
)

const NanosecondsPerMillisecond int64 = 1000000

The standard go time library supports nanoseconds since epoch time, not milliseconds. So we frequently convert.

Types

type CWEmbeddedMetricsManager

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

func NewCWEmbeddedMetrics

func NewCWEmbeddedMetrics(writer io.Writer) *CWEmbeddedMetricsManager

New returns a CWEmbeddedMetricsManager object that may be used to create metrics. Namespace is applied to all created metrics and maps to the CWEmbeddedMetricsManager namespace. Callers must ensure that regular calls to Send are performed, either manually or with one of the helper methods.

func (*CWEmbeddedMetricsManager) NewCounter

func (c *CWEmbeddedMetricsManager) NewCounter(name, unit string) Counter

NewCounter returns a counter. Observations are aggregated and emitted once per Sync invocation.

func (*CWEmbeddedMetricsManager) Run

func (c *CWEmbeddedMetricsManager) Run(ctx context.Context, interval time.Duration)

func (*CWEmbeddedMetricsManager) Sync

func (c *CWEmbeddedMetricsManager) Sync() error

Syncs metrics to the underlying system It will writer the metrics in the Embedded Metric Format https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html

type Counter

type Counter interface {
	With(dimensionValues ...string) Counter
	Add(delta float64)
}

type Dimension

type Dimension struct {
	Name  string
	Value string
}

Dimension represents the name and value of a given dimension. Each dimension must have its name in at least one DimensionSet to be recognized as a dimension.

type DimensionSet

type DimensionSet = []string

DimensionSet is a slice of strings containing the dimension names that will be applied to all metrics logged. The values within this slice MUST also be members on the root node, referred to as the Target Members

A DimensionSet MUST NOT contain more than 9 dimension keys.

The target member defines a dimension that will be published as part of the metric identity. Every DimensionSet used creates a new metric in CloudWatch.

type DimensionValues

type DimensionValues []string

DimensionValues is a type alias that provides validation on its With method. Metrics may include it as a member to help them satisfy With semantics and save some code duplication.

func (DimensionValues) With

func (lvs DimensionValues) With(dvs ...string) DimensionValues

With validates the input, and returns a new aggregate labelValues.

type DimensionsCounter

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

Counter is a counter. Observations are forwarded to a node object, and aggregated (summed) per timeseries.

func (*DimensionsCounter) Add

func (d *DimensionsCounter) Add(delta float64)

Add implements metrics.Counter.

func (*DimensionsCounter) With

func (d *DimensionsCounter) With(dvs ...string) Counter

With implements metrics.Counter.

type EmbeddedMetric

type EmbeddedMetric struct {
	// A slice of MetricDirectiveObjects used to instruct CloudWatch to extract metrics from the
	// root node of the LogEvent.
	CloudWatchMetrics []MetricDirectiveObject

	// A number representing the time stamp used for metrics extracted from the event. Values MUST
	// be expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
	Timestamp int64
}

EmbeddedMetric is the value mapped to the required top level member of the root node `_aws` in the AWS embedded metric format.

type Logger

type Logger interface {
	Log(dimensions []Dimension, values ...Metric)
}

func MustLogger

func MustLogger(dimensionSets []DimensionSet) Logger

MustLogger creates a new Logger based on the given input, and panics if the input is invalid

func NewLogger

func NewLogger(dimensionSets []DimensionSet) (Logger, error)

NewLogger create a new logger for a set of dimensions, returning an error if dimensions are invalid

type Manager

type Manager interface {
	// Runs the metric manager
	// It will sync the metrics every `interval` duration
	Run(ctx context.Context, interval time.Duration)
	// Returns a new Counter
	NewCounter(name, unit string) Counter
	// Sync the metrics to the underlying system
	Sync() error
}

Metrics manager

type Metric

type Metric struct {
	// A reference to a metric Target Member. Each Metric Name must also be a top level member.
	Name string

	// Valid Unit values (defaults to None):
	// Seconds | Microseconds | Milliseconds | Bytes | Kilobytes | Megabytes | Gigabytes | Terabytes
	// Bits | Kilobits | Megabits | Gigabits | Terabits | Percent | Count | Bytes/Second |
	// Kilobytes/Second | Megabytes/Second | Gigabytes/Second | Terabytes/Second | Bits/Second |
	// Kilobits/Second | Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None
	Unit string

	// This value is not marshalled to JSON as it is not part of the AWS embedded metric format. We
	// simply include it here for convenience when calling the loggers defined here, so that it is
	// not required to consider the value of a metric separate from its Name and Unit.
	Value interface{} `json:"-"`
}

Metric contains a name and a unit used to describe a particular metric value

type MetricDirectiveObject

type MetricDirectiveObject struct {
	// A string representing the CloudWatch namespace for the metric.
	Namespace string

	// A slice representing the collection of DimensionSets for the metric
	Dimensions []DimensionSet

	// A slice of Metric values and units. This slice MUST NOT contain more than 100 Metrics.
	Metrics []Metric
}

MetricDirectiveObject instructs downstream services that the LogEvent contains metrics that will be extracted and published to CloudWatch.

type Space

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

Space represents an N-dimensional vector space. Each name and unique label value pair establishes a new dimension and point within that dimension. Order matters, i.e. [a=1 b=2] identifies a different timeseries than [b=2 a=1].

func NewSpace

func NewSpace() *Space

NewSpace returns an N-dimensional vector space.

func (*Space) Observe

func (s *Space) Observe(name, unit string, dvs DimensionValues, value float64)

Observe locates the time series identified by the name and label values in the vector space, and appends the value to the list of observations.

func (*Space) Reset

func (s *Space) Reset() *Space

Reset empties the current space and returns a new Space with the old contents. Reset a Space to get an immutable copy suitable for walking.

func (*Space) Walk

func (s *Space) Walk(fn func(name, unit string, dvs DimensionValues, sum float64, count int64) bool)

Walk traverses the vector space and invokes fn for each non-empty time series which is encountered. Return false to abort the traversal.

type StaticLogger

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

StaticLogger conveniently stores repeatedly used embedded metric format configurations such as dimensionSets and metric name/unit so that they do not need to be specified each time. StaticLogger only supports one dimension set and one metric which must be set at initialization.

These limitations still allow for 90% of use cases, and are more suitable for performance critical parts of the code than the Logger.

func MustStaticLogger

func MustStaticLogger(dimensionSets []DimensionSet, metrics []Metric) *StaticLogger

MustStaticLogger creates a new StaticLogger based on the given input, and panics if the input is invalid

func NewStaticLogger

func NewStaticLogger(dimensionSets []DimensionSet, metrics []Metric) (*StaticLogger, error)

NewStaticLogger create a new logger for a given set of dimensions and metric, returning an error if the dimensions or metric are invalid

func (*StaticLogger) Log

func (l *StaticLogger) Log(metrics []Metric, dimensions ...Dimension)

Log sends a log formatted in the CloudWatch embedded metric format

func (*StaticLogger) LogSingle

func (l *StaticLogger) LogSingle(value interface{}, dimensions ...Dimension)

LogSingle sends a log for a single metric