metric

Documentation

Overview

Package metric is the API for defining metrics and updating their values.

When you define a metric you must also define the names and types of any fields on that metric. Additionally, you can specify the target type of the metric. It is an error to define two metrics with the same and target type. It will cause a panic if there are duplicated metrics.

When setting metric values, you must pass correct number of fields, with correct types, or the setter function will panic.

Example:

var (
  requests = metric.NewCounterWithOptions("myapp/requests",
    &metric.Options{TargetType: types.TaskType},
    "Number of requests",
    nil,
    field.String("status"),
)
...
func handleRequest() {
  if success {
    requests.Add(1, "success")
  } else {
    requests.Add(1, "failure")
  }
}

Index

• func InstrumentTransport(ctx context.Context, base http.RoundTripper, client string) http.RoundTripper
• func UpdateHTTPMetrics(ctx context.Context, name string, client string, code int, ...)
• func UpdateServerMetrics(ctx context.Context, name string, code int, duration time.Duration, ...)
• type Bool
  • func NewBool(name string, description string, metadata *types.MetricMetadata, ...) Bool
  • func NewBoolWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, ...) Bool
• type Counter
  • func NewCounter(name string, description string, metadata *types.MetricMetadata, ...) Counter
  • func NewCounterWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, ...) Counter
• type CumulativeDistribution
  • func NewCumulativeDistribution(name string, description string, metadata *types.MetricMetadata, ...) CumulativeDistribution
  • func NewCumulativeDistributionWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, ...) CumulativeDistribution
• type Float
  • func NewFloat(name string, description string, metadata *types.MetricMetadata, ...) Float
  • func NewFloatWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, ...) Float
• type FloatCounter
  • func NewFloatCounter(name string, description string, metadata *types.MetricMetadata, ...) FloatCounter
  • func NewFloatCounterWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, ...) FloatCounter
• type Int
  • func NewInt(name string, description string, metadata *types.MetricMetadata, ...) Int
  • func NewIntWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, ...) Int
• type NonCumulativeDistribution
  • func NewNonCumulativeDistribution(name string, description string, metadata *types.MetricMetadata, ...) NonCumulativeDistribution
  • func NewNonCumulativeDistributionWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, ...) NonCumulativeDistribution
• type Options
• type String
  • func NewString(name string, description string, metadata *types.MetricMetadata, ...) String
  • func NewStringWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, ...) String

Functions

func InstrumentTransport

func InstrumentTransport(ctx context.Context, base http.RoundTripper, client string) http.RoundTripper

InstrumentTransport returns a transport that sends HTTP client metrics via the given context.

If the context has no tsmon initialized (no metrics store installed), returns the original transport unchanged.

func UpdateHTTPMetrics

func UpdateHTTPMetrics(ctx context.Context, name string, client string,
	code int, duration time.Duration, requestBytes int64, responseBytes int64)

UpdateHTTPMetrics updates the metrics for a request to a remote server.

func UpdateServerMetrics

func UpdateServerMetrics(ctx context.Context, name string, code int,
	duration time.Duration, requestBytes int64, responseBytes int64,
	userAgent string)

UpdateServerMetrics updates the metrics for a handled request.

Types

type Bool

type Bool interface {
	types.Metric

	Get(ctx context.Context, fieldVals ...any) bool
	Set(ctx context.Context, v bool, fieldVals ...any)
}

Bool is a boolean-valued metric.

func NewBool

func NewBool(name string, description string, metadata *types.MetricMetadata, fields ...field.Field) Bool

NewBool returns a new bool-valued metric.

func NewBoolWithOptions

func NewBoolWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, fields ...field.Field) Bool

NewBoolWithOptions creates a new bool-valued metric with given Options.

Panics if metadata is set with a timestamp unit.

type Counter

type Counter interface {
	Int

	Add(ctx context.Context, n int64, fieldVals ...any)
}

Counter is a cumulative integer metric.

func NewCounter

func NewCounter(name string, description string, metadata *types.MetricMetadata, fields ...field.Field) Counter

NewCounter returns a new cumulative integer metric.

func NewCounterWithOptions

func NewCounterWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, fields ...field.Field) Counter

NewCounterWithOptions creates a new cumulative integer metric with given Options.

type CumulativeDistribution

type CumulativeDistribution interface {
	NonCumulativeDistribution

	Add(ctx context.Context, v float64, fieldVals ...any)
}

CumulativeDistribution is a cumulative-distribution-valued metric.

func NewCumulativeDistribution

func NewCumulativeDistribution(name string, description string, metadata *types.MetricMetadata, bucketer *distribution.Bucketer, fields ...field.Field) CumulativeDistribution

NewCumulativeDistribution returns a new cumulative-distribution-valued metric.

func NewCumulativeDistributionWithOptions

func NewCumulativeDistributionWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, bucketer *distribution.Bucketer, fields ...field.Field) CumulativeDistribution

NewCumulativeDistributionWithOptions creates a new cumulative-distribution-valued metric with given Options

type Float

type Float interface {
	types.Metric

	Get(ctx context.Context, fieldVals ...any) float64
	Set(ctx context.Context, v float64, fieldVals ...any)
}

Float is a non-cumulative floating-point gauge metric.

func NewFloat

func NewFloat(name string, description string, metadata *types.MetricMetadata, fields ...field.Field) Float

NewFloat returns a new non-cumulative floating-point gauge metric.

func NewFloatWithOptions

func NewFloatWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, fields ...field.Field) Float

NewFloatWithOptions creates a new non-cumulative floating-point gauge metric with given Options.

type FloatCounter

type FloatCounter interface {
	Float

	Add(ctx context.Context, n float64, fieldVals ...any)
}

FloatCounter is a cumulative floating-point metric.

func NewFloatCounter

func NewFloatCounter(name string, description string, metadata *types.MetricMetadata, fields ...field.Field) FloatCounter

NewFloatCounter returns a new cumulative floating-point metric.

func NewFloatCounterWithOptions

func NewFloatCounterWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, fields ...field.Field) FloatCounter

NewFloatCounterWithOptions creates a new cumulative floating-point metric with given Options.

type Int

type Int interface {
	types.Metric

	Get(ctx context.Context, fieldVals ...any) int64
	Set(ctx context.Context, v int64, fieldVals ...any)
}

Int is a non-cumulative integer gauge metric.

func NewInt

func NewInt(name string, description string, metadata *types.MetricMetadata, fields ...field.Field) Int

NewInt returns a new non-cumulative integer gauge metric.

func NewIntWithOptions

func NewIntWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, fields ...field.Field) Int

NewIntWithOptions creates a new non-cumulative integer gauge metric with given Options.

type NonCumulativeDistribution

type NonCumulativeDistribution interface {
	types.DistributionMetric

	Get(ctx context.Context, fieldVals ...any) *distribution.Distribution
	Set(ctx context.Context, d *distribution.Distribution, fieldVals ...any)
}

NonCumulativeDistribution is a non-cumulative-distribution-valued metric.

func NewNonCumulativeDistribution

func NewNonCumulativeDistribution(name string, description string, metadata *types.MetricMetadata, bucketer *distribution.Bucketer, fields ...field.Field) NonCumulativeDistribution

NewNonCumulativeDistribution returns a new non-cumulative-distribution-valued metric.

func NewNonCumulativeDistributionWithOptions

func NewNonCumulativeDistributionWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, bucketer *distribution.Bucketer, fields ...field.Field) NonCumulativeDistribution

NewNonCumulativeDistributionWithOptions creates a new non-cumulative-distribution-valued metric with given Options.

type Options

type Options struct {
	TargetType types.TargetType
	Registry   *registry.Registry
}

Options holds options to create a new metric.

type String

type String interface {
	types.Metric

	Get(ctx context.Context, fieldVals ...any) string
	Set(ctx context.Context, v string, fieldVals ...any)
}

String is a string-valued metric.

func NewString

func NewString(name string, description string, metadata *types.MetricMetadata, fields ...field.Field) String

NewString returns a new string-valued metric.

func NewStringWithOptions

func NewStringWithOptions(name string, opt *Options, description string, metadata *types.MetricMetadata, fields ...field.Field) String

NewStringWithOptions creates a new string-valued metric with given Options

Panics if metadata is set with a timestamp unit.