atomicstats

README

Atomic Stats

Agent components commonly need to track some runtime statistics about their operation, such as event counters. These statistics are often updated atomically, but need to be marshaled into various other forms for display in expvars, agent status, and so on.

This package package supports marshalling such structs into map[string]interface{}, including support for reading go.uber.org/atomic values.

Usage

To use it, create a struct containing the stats you want to track, and tag the fields with stats:"":

type telemetry struct {
	TracesReceived *atomic.Int64 `stats:""`
	TracesFiltered *atomic.Int64 `stats:""`
}

The struct can have any number of additional fields without the stats tag -- this package will ignore them.

To generate the map of telemetry data when required, call atomicstats.Report(tlm), passing an pointer to an instance of your struct type.

Documentation

Overview

Package atomicstats provides support for "stats" structs containing atomic values.

Example

// define a struct with some `stats` tags
type myStats struct {
	integer       int64         `stats:""`
	atomicInteger *atomic.Int64 `stats:""`
	notStats      int64
}

// create a myStats value
stats := myStats{
	integer:       10,
	atomicInteger: atomic.NewInt64(20),
	notStats:      30,
}
statsMap := Report(&stats)

fmt.Printf("%#v\n", statsMap)

Output:

map[string]interface {}{"atomic_integer":20, "integer":10}

Index

• func Report(v interface{}) map[string]interface{}

Examples

• Package

Functions

func Report

func Report(v interface{}) map[string]interface{}

Report returns a `map` representation of the stats in the given value. All map keys are converted to snake_case.

Such structs should tag fields to be included in the stats with `stats:""`. Stats fields can be of any of the following types:

int
int8
int16
int32
int64
uint
uint8
uint16
uint32
uint64
uintptr
go.uber.org/atomic.Bool
go.uber.org/atomic.Duration
go.uber.org/atomic.Error
go.uber.org/atomic.Float64
go.uber.org/atomic.Int32
go.uber.org/atomic.Int64
go.uber.org/atomic.String
go.uber.org/atomic.Time
go.uber.org/atomic.Uint32
go.uber.org/atomic.Uint64
go.uber.org/atomic.Uintptr
go.uber.org/atomic.UnsafePointer
go.uber.org/atomic.Value