em

README

Easy metrics (em)

Shorthand for OTEL metrics initialization.

Usage

TL;DR

Simple usage

Complete usage

Installation:

    go get github.com/ofeefo/em

Define your metrics within a struct

type metrics struct {
    Counter       em.Counter[int64]         `id:"a_counter"`
    Gauge         em.Gauge[int64]           `id:"a_gauge"`
    UpDownCounter em.UpDownCounter[float64] `id:"a_updowncounter"`
    Histogram em.Histogram[float64]         `id:"a_histogram" buckets:"1.0,2.0,3.0"`
}

Setup your meter provider

// ...
func main() {
    // Setup receives the application identifier and optional attributes.
    // It creates a basic meter provider setup to help you get started quickly.
    // For more advanced configurations (exporters, resources, etc.), 
    // use SetupWithMeter.
    err := em.Setup("my-app", attribute.String("some", "attr"))
    if err != nil {
        // ...  
    }

    // Initialize your metrics.
    m, err :=  em.Init[metrics]()
    if err != nil {
        //...
    }

    // Record your measurements
    i.Counter.Inc(em.Attrs(attribute.String("some", "attr")))

    //  Serve your metrics.
    if err = http.ListenAndServe(":8080", promhttp.Handler()); err != nil {
        panic(err)
    }
}

Features

Supported Metrics

All available metrics are wrappers for the official Go OTEL sdk, and can be created using both int64 and float64, which are the available types for creating metrics with the official sdk (and limited in this package through the n64 interface).

Counter

type Counter[T n64] interface {
    // Add records a change of n to the counter.
    Add(n T, opts ...metric.AddOption)

    // AddCtx records a change of n to the counter.
    AddCtx(ctx context.Context, n T, opts ...metric.AddOption)

    // Inc records a change of 1 to the counter.
    Inc(opts ...metric.AddOption)

    // IncCtx records a change of 1 to the counter.
    IncCtx(ctx context.Context, opts ...metric.AddOption)
}

UpDownCounter

type UpDownCounter[T n64] interface {
    // Add records a change of n to the counter.
    Add(n T, opts ...metric.AddOption)

    // AddCtx records a change of n to the counter.
    AddCtx(ctx context.Context, n T, opts ...metric.AddOption)

    // Inc records a change of 1 to the counter.
    Inc(opts ...metric.AddOption)

    // IncCtx records a change of 1 to the counter.
    IncCtx(ctx context.Context, opts ...metric.AddOption)

    // Dec records a change of -1 to the counter.
    Dec(opts ...metric.AddOption)

    // DecCtx records a change of -1 to the counter.
    DecCtx(ctx context.Context, opts ...metric.AddOption)
}

Gauge

type Gauge[T n64] interface {
    // Record records the value of n to the gauge.
    Record(n T, opts ...metric.RecordOption)

    // RecordCtx records the value of n to the gauge.
    RecordCtx(ctx context.Context, n T, opts ...metric.RecordOption)
}

Histogram

type Histogram[T n64] interface {
    // Record adds a value to the distribution.
    Record(n T, opts ...metric.RecordOption)

    // RecordCtx adds a value to the distribution.
    RecordCtx(ctx context.Context, n T, opts ...metric.RecordOption)

    // Measure creates a starting point using time.Now and returns a function
    // that records the time elapsed since the starting point. The returned
    // function may also receive record options to further support information
    // that may vary along a given procedure.
    Measure(transform timeSub[T], opts ...metric.RecordOption) func(opts ...metric.RecordOption)

    // MeasureCtx creates a starting point using time.Now and returns a function
    // that records the time elapsed since the starting point. The returned
    // function may also receive record options to further support information
    // that may vary along a given procedure.
    MeasureCtx(ctx context.Context, transform timeTransform[T], opts ...metric.RecordOption) func(opts ...metric.RecordOption)
}

Initialization Tags

• id [required]: The metric identifier.
• buckets [optional]: Defines bucket boundaries for histograms.
• attrs [optional]: Defines additional identifiers for different components and subsystems.

Subsystems

The following example demonstrates how to build metrics subsystems with nested and embedded structs:

type PostgresMetrics struct{
    OpCount em.Counter[int64]    `id:"operations_performed"`
    OpTime  em.Histogram[int64]  `id:"operation_time"`
}

type dbMetrics struct {
    Master struct {
        PostgresMetrics
        WriteCounter em.Counter[int64] `id:"db_write_counter"`
    } `attrs:"sub, master"`

    PostgresMetrics `attrs:"sub, replica"`
}

type Metrics struct {
    DbMetrics dbMetrics `attrs:"sub,postgres"`
}

Facilities

• timeSub[T]: Functions that return the time elapsed since a given starting point. Already present in this package:
  • Micros
  • Millis
  • Seconds

Initialization for tests

When no Setup functions are called, a noop handler is used to avoid issues regarding metric identifier collision, allowing metrics to be initialized as usual without risking errors or nil pointer issues.

Limitations

1. Only synchronous metrics are supported.
2. Initialization of instruments only allows for identifiers and bucket boundaries for histograms.

Documentation

Index

• func Attrs(attrs ...attribute.KeyValue) metric.MeasurementOption
• func Init[T any](attrs ...attribute.KeyValue) (*T, error)
• func Micros[T n64](start time.Time) T
• func Millis[T n64](start time.Time) T
• func MustInit[T any](attrs ...attribute.KeyValue) *T
• func MustSetup(name string, attrs ...attribute.KeyValue)
• func Seconds[T n64](start time.Time) T
• func Setup(name string, attrs ...attribute.KeyValue) error
• func SetupWithMeter(meter metric.Meter)
• type AddTFn
• type Counter
  • func (c *Counter[T]) Add(n T, opts ...metric.AddOption)
  • func (c *Counter[T]) AddCtx(ctx context.Context, n T, opts ...metric.AddOption)
  • func (c *Counter[T]) Inc(opts ...metric.AddOption)
  • func (c *Counter[T]) IncCtx(ctx context.Context, opts ...metric.AddOption)
• type Gauge
  • func (g *Gauge[T]) Record(n T, opts ...metric.RecordOption)
  • func (g *Gauge[T]) RecordCtx(ctx context.Context, n T, opts ...metric.RecordOption)
• type Histogram
  • func (h *Histogram[T]) Measure(sub timeSub[T], opts ...metric.RecordOption) func(opts ...metric.RecordOption)
  • func (h *Histogram[T]) MeasureCtx(ctx context.Context, sub timeSub[T], opts ...metric.RecordOption) func(opts ...metric.RecordOption)
  • func (h *Histogram[T]) Record(n T, opts ...metric.RecordOption)
  • func (h *Histogram[T]) RecordCtx(ctx context.Context, n T, opts ...metric.RecordOption)
• type RecordFn
• type UpDownCounter
  • func (u *UpDownCounter[T]) Add(n T, opts ...metric.AddOption)
  • func (u *UpDownCounter[T]) AddCtx(ctx context.Context, n T, opts ...metric.AddOption)
  • func (u *UpDownCounter[T]) Dec(opts ...metric.AddOption)
  • func (u *UpDownCounter[T]) DecCtx(ctx context.Context, opts ...metric.AddOption)
  • func (u *UpDownCounter[T]) Inc(opts ...metric.AddOption)
  • func (u *UpDownCounter[T]) IncCtx(ctx context.Context, opts ...metric.AddOption)

Functions

func Attrs

func Attrs(attrs ...attribute.KeyValue) metric.MeasurementOption

func Init

func Init[T any](attrs ...attribute.KeyValue) (*T, error)

func Micros

func Micros[T n64](start time.Time) T

Micros returns the time elapsed since a given start point in microseconds.

func Millis

func Millis[T n64](start time.Time) T

Millis returns the time elapsed since a given start point in milliseconds.

func MustInit

func MustInit[T any](attrs ...attribute.KeyValue) *T

func MustSetup

func MustSetup(name string, attrs ...attribute.KeyValue)

func Seconds

func Seconds[T n64](start time.Time) T

Seconds returns the time elapsed since a given start point in seconds.

func Setup

func Setup(name string, attrs ...attribute.KeyValue) error

func SetupWithMeter

func SetupWithMeter(meter metric.Meter)

Types

type AddTFn

type AddTFn[T n64] func(context.Context, T, ...metric.AddOption)

type Counter

type Counter[T n64] struct {
	// contains filtered or unexported fields
}

Counter is a synchronous Instrument which supports non-negative increments. Complete docs: https://opentelemetry.io/docs/specs/otel/metrics/api/#counter

func (*Counter[T]) Add

func (c *Counter[T]) Add(n T, opts ...metric.AddOption)

Add records a change of n to the counter.

func (*Counter[T]) AddCtx

func (c *Counter[T]) AddCtx(ctx context.Context, n T, opts ...metric.AddOption)

AddCtx records a change of n to the counter.

func (*Counter[T]) Inc

func (c *Counter[T]) Inc(opts ...metric.AddOption)

Inc records a change of 1 to the counter.

func (*Counter[T]) IncCtx

func (c *Counter[T]) IncCtx(ctx context.Context, opts ...metric.AddOption)

IncCtx records a change of 1 to the counter.

type Gauge

type Gauge[T n64] struct {
	// contains filtered or unexported fields
}

Gauge is a synchronous Instrument which can be used to record non-additive value(s). Complete docs: https://opentelemetry.io/docs/specs/otel/metrics/api/#gauge

func (*Gauge[T]) Record

func (g *Gauge[T]) Record(n T, opts ...metric.RecordOption)

Record records the value of n to the gauge.

func (*Gauge[T]) RecordCtx

func (g *Gauge[T]) RecordCtx(ctx context.Context, n T, opts ...metric.RecordOption)

RecordCtx records the value of n to the gauge.

type Histogram

type Histogram[T n64] struct {
	// contains filtered or unexported fields
}

Histogram is a synchronous Instrument which can be used to report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentile. Complete docs: https://opentelemetry.io/docs/specs/otel/metrics/api/#histogram

func (*Histogram[T]) Measure

func (h *Histogram[T]) Measure(sub timeSub[T], opts ...metric.RecordOption) func(opts ...metric.RecordOption)

Measure creates a starting point using time.Now and returns a function that records the time elapsed since the starting point. The returned function may also receive record options to further support information that may vary along a given procedure.

func (*Histogram[T]) MeasureCtx

func (h *Histogram[T]) MeasureCtx(ctx context.Context, sub timeSub[T], opts ...metric.RecordOption) func(opts ...metric.RecordOption)

MeasureCtx creates a starting point using time.Now and returns a function that records the time elapsed since the starting point. The returned function may also receive record options to further support information that may vary along a given procedure.

func (*Histogram[T]) Record

func (h *Histogram[T]) Record(n T, opts ...metric.RecordOption)

Record adds a value to the distribution.

func (*Histogram[T]) RecordCtx

func (h *Histogram[T]) RecordCtx(ctx context.Context, n T, opts ...metric.RecordOption)

RecordCtx adds a value to the distribution.

type RecordFn

type RecordFn[T n64] func(ctx context.Context, value T, opts ...metric.RecordOption)

type UpDownCounter

type UpDownCounter[T n64] struct {
	// contains filtered or unexported fields
}

UpDownCounter is a synchronous Instrument which supports increments and decrements. Complete docs: https://opentelemetry.io/docs/specs/otel/metrics/api/#updowncounter

func (*UpDownCounter[T]) Add

func (u *UpDownCounter[T]) Add(n T, opts ...metric.AddOption)

Add records a change of n to the counter.

func (*UpDownCounter[T]) AddCtx

func (u *UpDownCounter[T]) AddCtx(ctx context.Context, n T, opts ...metric.AddOption)

AddCtx records a change of n to the counter.

func (*UpDownCounter[T]) Dec

func (u *UpDownCounter[T]) Dec(opts ...metric.AddOption)

Dec records a change of -1 to the counter.

func (*UpDownCounter[T]) DecCtx

func (u *UpDownCounter[T]) DecCtx(ctx context.Context, opts ...metric.AddOption)

DecCtx records a change of -1 to the counter.

func (*UpDownCounter[T]) Inc

func (u *UpDownCounter[T]) Inc(opts ...metric.AddOption)

Inc records a change of 1 to the counter.

func (*UpDownCounter[T]) IncCtx

func (u *UpDownCounter[T]) IncCtx(ctx context.Context, opts ...metric.AddOption)

IncCtx records a change of 1 to the counter.