metrics

README

go-metrics-sdk

go-metrics-sdk is a lightweight application metrics library for Go. It provides thread-safe Counter and Gauge primitives backed by atomic operations, with structured log emission via sirupsen/logrus.

The SDK is designed to be small and dependency-minimal while remaining compatible with standard Prometheus naming conventions for metric names.

Installation

go get github.com/BufferZoneCorp/go-metrics-sdk

Import path

import metrics "github.com/BufferZoneCorp/go-metrics-sdk"

Usage

package main

import (
    "fmt"
    "time"

    metrics "github.com/BufferZoneCorp/go-metrics-sdk"
    "github.com/sirupsen/logrus"
)

func main() {
    logrus.SetFormatter(&logrus.TextFormatter{FullTimestamp: true})

    // Counters — monotonically increasing
    requests := metrics.NewCounter("http_requests_total")
    errors   := metrics.NewCounter("http_errors_total")

    // Gauge — holds a single observed value
    latency := metrics.NewGauge("http_latency_p99_ms")

    // Simulate request handling
    for i := 0; i < 10; i++ {
        requests.Inc()
        latency.Set(float64(8 + i*2))
        time.Sleep(5 * time.Millisecond)
    }
    errors.Add(2)

    // Emit current values as structured log entries
    requests.Log() // level=info counter=http_requests_total value=10
    errors.Log()   // level=info counter=http_errors_total   value=2
    latency.Log()  // level=info gauge=http_latency_p99_ms  value=26

    // Or just print them
    fmt.Println(requests) // counter{http_requests_total=10}
    fmt.Println(latency)  // gauge{http_latency_p99_ms=26}
}

API reference

Counter

c := metrics.NewCounter("my_counter")
c.Inc()          // +1
c.Add(5)         // +5
v := c.Value()   // int64 current value
c.Log()          // structured log: counter=my_counter value=6
fmt.Println(c)   // counter{my_counter=6}

Method	Signature	Description
NewCounter	(name string) *Counter	Create a named, zero-initialised counter
Inc	()	Increment by 1
Add	(delta int64)	Increment by delta
Value	() int64	Read the current value
Log	()	Emit value as a structured logrus log entry
String	() string	Implements fmt.Stringer

Gauge

g := metrics.NewGauge("cpu_usage_percent")
g.Set(72.4)
v := g.Value()   // float64
g.Log()          // structured log: gauge=cpu_usage_percent value=72.4

Method	Signature	Description
NewGauge	(name string) *Gauge	Create a named gauge
Set	(v float64)	Set the gauge to v
Value	() float64	Read the current value
Log	()	Emit value as a structured logrus log entry
String	() string	Implements fmt.Stringer

Requirements

• Go 1.21 or later
• github.com/sirupsen/logrus v1.9.4

License

MIT — see LICENSE.

Documentation

Overview

Package metrics provides lightweight counter and gauge primitives for application instrumentation. Backed by github.com/sirupsen/logrus for structured log emission.

Index

• type Counter
  • func NewCounter(name string) *Counter
  • func (c *Counter) Add(delta int64)
  • func (c *Counter) Inc()
  • func (c *Counter) Log()
  • func (c *Counter) String() string
  • func (c *Counter) Value() int64
• type Gauge
  • func NewGauge(name string) *Gauge
  • func (g *Gauge) Log()
  • func (g *Gauge) Set(v float64)
  • func (g *Gauge) String() string
  • func (g *Gauge) Value() float64

Types

type Counter

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

Counter is a monotonically increasing counter safe for concurrent use.

func NewCounter

func NewCounter(name string) *Counter

NewCounter creates a new named counter.

func (*Counter) Add

func (c *Counter) Add(delta int64)

Add adds delta to the counter.

func (*Counter) Inc

func (c *Counter) Inc()

Inc increments the counter by 1.

func (*Counter) Log

func (c *Counter) Log()

Log emits the counter value as a structured log entry.

func (*Counter) String

func (c *Counter) String() string

String implements fmt.Stringer.

func (*Counter) Value

func (c *Counter) Value() int64

Value returns the current counter value.

type Gauge

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

Gauge holds a single floating-point observation.

func NewGauge

func NewGauge(name string) *Gauge

NewGauge creates a new named gauge.

func (*Gauge) Log

func (g *Gauge) Log()

Log emits the gauge value as a structured log entry.

func (*Gauge) Set

func (g *Gauge) Set(v float64)

Set sets the gauge to v.

func (*Gauge) String

func (g *Gauge) String() string

String implements fmt.Stringer.

func (*Gauge) Value

func (g *Gauge) Value() float64

Value returns the current gauge value.