Update docs

Author: ofeefo

README.md

@@ -1,49 +1,50 @@
 # Easy metrics (em)
-Shorthand for [OTEL](https://github.com/open-telemetry/opentelemetry-go) instrumentation initialization.
-<br>
+Shorthand for [OTEL](https://github.com/open-telemetry/opentelemetry-go) metrics
+initialization.
+
+
 ## Usage
 ### TL;DR
 #### [Simple usage](./example/simple_usage/main.go)
 #### [Complete usage](./example/complete_usage/main.go)
 
-### Get the dependency:
+### Installation:
 ```bash
     go get github.com/ofeefo/em
 ```
 
-### Define your instruments in a struct
+### Define your metrics within a struct
 ```go
-type instruments struct{
-    Counter64       em.I64Counter   `id:"my_counter"`
-    UpDownCounter64 em.I64Counter   `id:"my_updown_counter"`
-    GaugeF64        em.F64Gauge     `id:"my_gauge"`
-    // Histograms can use the 'buckets' tag to define explicit boundaries.
-    HistogramF64 em.F64Histogram    `id:"i_am_a_histogram" buckets:"1.0,2.0,3.0"`
+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"`
 }
 ```
 
-### When initializing your app
+### Setup your meter provider
 
 ```go
 // ...
-func main(){
+func main() {
     // Setup receives the application identifier and optional attributes.
-    // It creates a basic OTEL setup to help you get started quickly.
-    // For more advanced configurations (exporters, resources, etc.), use SetupWithMeter.
+    // 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 instruments.
-    // There's also a MustInit function, which will panic if initialization fails.
-    i, err :=  em.Init[instruments]()
+    // Initialize your metrics.
+    m, err :=  em.Init[metrics]()
     if err != nil {
         //...
     }
 
     // Record your measurements
-    i.Counter64.Add(1, em.Attrs(attribute.String("some", "attr")))
+    i.Counter.Inc(em.Attrs(attribute.String("some", "attr")))
 
     //  Serve your metrics.
     if err = http.ListenAndServe(":8080", promhttp.Handler()); err != nil {
@@ -53,46 +54,129 @@ func main(){
 ```
 
 ## Features
-### Supported tags
-#### Instruments
-* `id [required]`: The instrument identifier.
-* `buckets [optional]`: Defines bucket boundaries for histograms.
+### Supported Metrics
+All available metrics are wrappers for the official [Go OTEL sdk](https://github.com/open-telemetry/opentelemetry-go),
+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).
 
-#### Nested or Embedded structs:
-  * `attrs [optional]`: Comma-separated string attributes to identify specific instruments sets.
+### Counter
+```go
+type Counter[T n64] interface {
+    // Add records a change of n to the counter.
+    Add(n T, opts ...metric.AddOption)
 
-### Supported instruments [int64/float64]:
-* `Counter`
-* `UpDownCounter`
-* `Gauge`
-* `Histogram`
+    // AddCtx records a change of n to the counter.
+    AddCtx(ctx context.Context, n T, opts ...metric.AddOption)
 
-### Nested & Embedded structs
-The following example demonstrates how nested and embedded structs are supported:
+    // 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
 ```go
-type Embedded struct {
-    Histogram     em.I64Histogram     `id:"example_embedded_histogram"`
-    UpDownCounter em.F64UpDownCounter `id:"example_embedded_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
+```go
+type Gauge[T n64] interface {
+    // Record records the value of n to the gauge.
+    Record(n T, opts ...metric.RecordOption)
 
-type nested struct {
-    Counter  em.F64Counter `id:"example_nested_counter"`
-    Gauge    em.F64Gauge   `id:"example_nested_gauge"`
-    MoreNest struct {
-        Counter em.F64Counter `id:"example_more_nested_counter"`
-    }
+    // RecordCtx records the value of n to the gauge.
+    RecordCtx(ctx context.Context, n T, opts ...metric.RecordOption)
+}
+
+```
+### Histogram
+```go
+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).
+
+### Subsystems
+The following example demonstrates how to build metrics subsystems with nested 
+and embedded structs:
+```go
+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 samplers struct {
-    // Nested and embedded structs (and struct pointers) are supported.
-    // Instruments in these structs inherit attributes both from the parent struct
-    // initialization and through the 'attrs' tag.
-    *Embedded `attrs:"sub,embedded"`
-    Nested    nested `attrs:"sub,nested"`
+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`.
 
 
 

base.go

@@ -10,8 +10,11 @@ import (
 	"go.opentelemetry.io/otel/metric"
 )
 
+// timeSub are functions that returns the time elapsed since a given starting
+// point.
 type timeSub[T n64] func(start time.Time) T
 
+// n64 represents available types for creating metrics.
 type n64 interface {
 	int64 | float64
 }

counter.go

@@ -8,6 +8,9 @@ import (
 	"go.opentelemetry.io/otel/metric"
 )
 
+// Counter is a synchronous Instrument which supports non-negative increments.
+// Complete docs:
+// https://opentelemetry.io/docs/specs/otel/metrics/api/#counter
 type Counter[T n64] interface {
 	// Add records a change of n to the counter.
 	Add(n T, opts ...metric.AddOption)

example/complete_usage/main.go

@@ -52,8 +52,8 @@ func main() {
 	go func() {
 		var i int64
 		j := func() float64 { return float64(i) }
-		done1 := s.Histogram.Measure(millis[float64], em.Attrs(attribute.String("your", "attr")))
-		done2 := s2.Histogram.Measure(millis[float64], em.Attrs(attribute.String("your", "attr")))
+		done1 := s.Histogram.Measure(em.Millis[float64], em.Attrs(attribute.String("your", "attr")))
+		done2 := s2.Histogram.Measure(em.Millis[float64], em.Attrs(attribute.String("your", "attr")))
 		for i = range 10 {
 			// Layer 1 instruments
 			s.Counter.Add(i, em.Attrs(attribute.String("your", "attr")))
@@ -94,7 +94,3 @@ func main() {
 		panic(err)
 	}
 }
-
-func millis[T float64 | int64](start time.Time) T {
-	return T(time.Since(start).Milliseconds())
-}

gauge.go

@@ -8,6 +8,9 @@ import (
 	"go.opentelemetry.io/otel/metric"
 )
 
+// 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
 type Gauge[T n64] interface {
 	// Record records the value of n to the gauge.
 	Record(n T, opts ...metric.RecordOption)

histogram.go

@@ -9,6 +9,11 @@ import (
 	"go.opentelemetry.io/otel/metric"
 )
 
+// 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
 type Histogram[T n64] interface {
 	// Record adds a value to the distribution.
 	Record(n T, opts ...metric.RecordOption)

updown_counter.go

@@ -8,6 +8,9 @@ import (
 	"go.opentelemetry.io/otel/metric"
 )
 
+// UpDownCounter is a synchronous Instrument which supports increments and decrements.
+// Complete docs:
+// https://opentelemetry.io/docs/specs/otel/metrics/api/#updowncounter
 type UpDownCounter[T n64] interface {
 	// Add records a change of n to the counter.
 	Add(n T, opts ...metric.AddOption)

utils.go

@@ -11,14 +11,17 @@ func Attrs(attrs ...attribute.KeyValue) metric.MeasurementOption {
 	return metric.WithAttributes(attrs...)
 }
 
+// Millis returns the time elapsed since a given start point in milliseconds.
 func Millis[T n64](start time.Time) T {
 	return T(time.Since(start).Milliseconds())
 }
 
+// Micros returns the time elapsed since a given start point in microseconds.
 func Micros[T n64](start time.Time) T {
 	return T(time.Since(start).Milliseconds())
 }
 
+// Seconds returns the time elapsed since a given start point in seconds.
 func Seconds[T n64](start time.Time) T {
 	return T(time.Since(start).Seconds())
 }