telemetry

type DerivedMetric interface {
	// Name returns the name value of a DerivedMetric.
	Name() string

	// ValueFrom is used to update the derived value with the provided
	// function and the associated label values. If the metric is unlabeled,
	// ValueFrom may be called without any labelValues. Otherwise, the labelValues
	// supplied MUST match the label keys supplied at creation time both in number
	// and in order.
	ValueFrom(valueFn func() float64, labelValues ...LabelValue) DerivedMetric
}

type DerivedMetricSink interface {
	// NewDerivedGauge intents to create a new Metric with an aggregation type
	// of LastValue. That means that data collected by the new Metric will
	// export only the last recorded value.
	// Unlike NewGauge, the DerivedGauge accepts functions which are called to
	// get the current value.
	NewDerivedGauge(name, description string) DerivedMetric
}

type Label interface {
	// Insert will insert the provided value for the Label if not set.
	Insert(value string) LabelValue

	// Update will update the Label with provided value if already set.
	Update(value string) LabelValue

	// Upsert will insert or replace the provided value for the Label.
	Upsert(value string) LabelValue

	// Delete will remove the Label's value.
	Delete() LabelValue
}

type LabelValue interface{}

type Level int32

type Logger interface {
	// Debug logging with key-value pairs. Don't be shy, use it.
	Debug(msg string, keyValuePairs ...interface{})

	// Info logging with key-value pairs. This is for informational, but not
	// directly actionable conditions. It is highly recommended you attach a
	// Metric to these types of messages. Where a single informational or
	// warning style message might not be reason for action, a change in
	// occurrence does warrant action. By attaching a Metric for these logging
	// situations, you make this easy through histograms, thresholds, etc.
	Info(msg string, keyValuePairs ...interface{})

	// Error logging with key-value pairs. Use this when application state and
	// stability are at risk. These types of conditions are actionable and often
	// alerted on. It is very strongly encouraged to add a Metric to each of
	// these types of messages. Metrics provide the easiest way to coordinate
	// processing of these concerns and triggering alerting systems through your
	// metrics backend.
	Error(msg string, err error, keyValuePairs ...interface{})

	// SetLevel provides the ability to set the desired logging level.
	// This function can be used at runtime and must be safe for concurrent use.
	//
	// Note for Logger implementations, When creating a new Logger with the
	// With, Context, or Metric methods, the level should be set-able for all
	// from any of the Loggers sharing the same root Logger.
	SetLevel(lvl Level)

	// Level returns the currently configured logging level.
	Level() Level

	// With returns a new Logger decorated with the provided key-value pairs.
	With(keyValuePairs ...interface{}) Logger

	// Context returns a new Logger having access to Context for inclusion of
	// registered key-value pairs found in Context. If a Metric is also attached
	// to the Logger, the Metric LabelValue directives found in Context will
	// also be processed.
	Context(ctx context.Context) Logger

	// Metric returns a new Logger which will emit a measurement for the
	// provided Metric when the Log level is either Info or Error.
	// **Note** that in the event the Logger is set to only output Error level
	// messages, Info messages even though silenced from a logging perspective,
	// will still emit their Metric measurements.
	Metric(m Metric) Logger

	// Clone returns a new Logger based on the original implementation.
	Clone() Logger
}

type Metric interface {
	// Increment records a value of 1 for the current Metric.
	// For Sums, this is equivalent to adding 1 to the current value.
	// For Gauges, this is equivalent to setting the value to 1.
	// For Distributions, this is equivalent to making an observation of value 1.
	Increment()

	// Decrement records a value of -1 for the current Metric.
	// For Sums, this is equivalent to subtracting -1 to the current value.
	// For Gauges, this is equivalent to setting the value to -1.
	// For Distributions, this is equivalent to making an observation of value -1.
	Decrement()

	// Name returns the name value of a Metric.
	Name() string

	// Record makes an observation of the provided value for the given Metric.
	// LabelValues added through With will be processed in sequence.
	Record(value float64)

	// RecordContext makes an observation of the provided value for the given
	// Metric.
	// If LabelValues for registered Labels are found in context, they will be
	// processed in sequence, after which the LabelValues added through With
	// are handled.
	RecordContext(ctx context.Context, value float64)

	// With returns the Metric with the provided LabelValues encapsulated. This
	// allows creating a set of pre-dimensioned data for recording purposes.
	// It also allows a way to clear out LabelValues found in an attached
	// Context if needing to sanitize.
	With(labelValues ...LabelValue) Metric
}

type MetricOption func(*MetricOptions)

type MetricOptions struct {
	// EnabledCondition can hold a function which decides if metric is enabled.
	EnabledCondition func() bool
	// Unit holds the unit specifier of a Metric.
	Unit Unit
	// Labels holds the registered dimensions for the Metric.
	Labels []Label
}

type MetricSink interface {
	// NewSum intents to create a new Metric with an aggregation type of Sum
	// (the values will be cumulative). That means that data collected by the
	// new Metric will be summed before export.
	NewSum(name, description string, opts ...MetricOption) Metric

	// NewGauge intents to creates a new Metric with an aggregation type of
	// LastValue. That means that data collected by the new Metric will export
	// only the last recorded value.
	NewGauge(name, description string, opts ...MetricOption) Metric

	// NewDistribution intents to create a new Metric with an aggregation type
	// of Distribution. This means that the data collected by the Metric will be
	// collected and exported as a histogram, with the specified bounds.
	NewDistribution(name, description string, bounds []float64, opts ...MetricOption) Metric

	// NewLabel creates a new Label to be used as a metrics dimension.
	NewLabel(name string) Label

	// ContextWithLabels takes the existing LabelValue collection found in
	// Context and appends the Label operations as received from the provided
	// values on top, which is then added to the returned Context. The function
	// can return an error in case the provided values contain invalid label
	// names.
	ContextWithLabels(ctx context.Context, values ...LabelValue) (context.Context, error)
}

type OnGlobalMetricSinkFn func(m MetricSink)

type Unit string