debugstats: add package example, and test

Author: kevinburkesegment

README.md

@@ -181,9 +181,15 @@ func main() {
 Use the `debugstats` package to print all stats to the console.
 
 ```go
-handler := debugstats.Client{Dst: os.Stdout}
+handler := &debugstats.Client{Dst: os.Stdout}
+// to use as a standalone engine:
 engine := stats.NewEngine("engine-name", handler)
 engine.Incr("server.start")
+// or, register on the default stats engine:
+stats.Register(handler)
+
+// Sample output:
+// server.start:1|c
 ```
 
 You can use the `Grep` property to filter the printed metrics for only ones you
@@ -203,7 +209,7 @@ Monitoring
 > `go_version` in v4.6.0.
 
 The
-[github.com/segmentio/stats/procstats](https://godoc.org/github.com/segmentio/stats/procstats)
+[github.com/segmentio/stats/v5/procstats](https://godoc.org/github.com/segmentio/stats/v5/procstats)
 package exposes an API for creating a statistics collector on local processes.
 Statistics are collected for the current process and metrics including Goroutine
 count and memory usage are reported.
@@ -249,7 +255,7 @@ func main() {
 
 ### HTTP Servers
 
-The [github.com/segmentio/stats/httpstats](https://godoc.org/github.com/segmentio/stats/httpstats)
+The [github.com/segmentio/stats/v5/httpstats](https://godoc.org/github.com/segmentio/stats/v5/httpstats)
 package exposes a decorator of `http.Handler` that automatically adds metric
 collection to a HTTP handler, reporting things like request processing time,
 error counters, header and body sizes...
@@ -284,7 +290,7 @@ func main() {
 
 ### HTTP Clients
 
-The [github.com/segmentio/stats/httpstats](https://godoc.org/github.com/segmentio/stats/httpstats)
+The [github.com/segmentio/stats/v5/httpstats](https://godoc.org/github.com/segmentio/stats/v5/httpstats)
 package exposes a decorator of `http.RoundTripper` which collects and reports
 metrics for client requests the same way it's done on the server side.
 

debugstats/debugstats.go

@@ -1,8 +1,50 @@
-// Package debugstats simplifies metric troubleshooting by sending metrics to
-// any io.Writer.
+// Package debugstats is a very small helper that makes it easy to **see** the
+// raw metrics produced by github.com/segmentio/stats/v5 while you are debugging
+// or developing a new instrumentation strategy.
 //
-// By default, metrics will be printed to os.Stdout. Use the Dst and Grep fields
-// to customize the output as appropriate.
+//   - It implements the stats.Handler interface.
+//   - Every metric that reaches the handler is written as a single line in a
+//     StatsD-like format (metric name, value, type, tags) followed by '\n'.
+//   - A time-stamp (RFC-3339) is prepended so that the stream can later be
+//     correlated with logs if desired.
+//
+// # Destination
+//
+// By default the lines are written to os.Stdout, but any io.Writer can be
+// supplied through the Client’s Dst field:
+//
+//	var buf bytes.Buffer
+//	stats.Register(&debugstats.Client{Dst: &buf}) // write into a buffer
+//
+// # Grep-like filtering
+//
+// When you are only interested in a subset of your metrics you can pass a
+// regular expression via the Grep field.  Only the lines whose *full textual
+// representation* match the regexp are emitted:
+//
+//	stats.Register(&debugstats.Client{
+//	    Grep: regexp.MustCompile(`^my_service\.http_requests_total`),
+//	})
+//
+// Quick example
+//
+//	func main() {
+//	    stats.Register(&debugstats.Client{})    // defaults to stdout
+//
+//	    stats.Set("active_users", 42)
+//	    stats.Observe("compression_ratio", 0.28,
+//	        stats.T("codec", "zstd"),
+//	        stats.T("bucket", "10-100 kB"),
+//	    )
+//
+//	    // Flush whenever you need a consistent snapshot:
+//	    stats.Flush()
+//	}
+//
+// Typical output (wrapped for readability):
+//
+//	2024-04-18T09:45:00Z active_users:42|g
+//	2024-04-18T09:45:00Z compression_ratio:0.28|d|#bucket:10-100 kB,codec:zstd
 package debugstats
 
 import (

debugstats/example_test.go

@@ -0,0 +1,25 @@
+package debugstats_test
+
+import (
+	"regexp"
+
+	"github.com/segmentio/stats/v5"
+	"github.com/segmentio/stats/v5/debugstats"
+)
+
+// ExampleClient demonstrates how to register a debugstats.Client so that all
+// produced metrics are echoed to stdout.  The example purposefully omits an
+// output check because the first column is a time-stamp whose value varies.
+func ExampleClient() {
+	// Only show metrics whose name contains "foo".
+	stats.Register(&debugstats.Client{
+		Grep: regexp.MustCompile(`foo`),
+	})
+
+	stats.Set("foo_active_users", 123)
+	stats.Observe("bar_compression_ratio", 0.37) // <- this one is filtered out
+
+	// Flush to make sure the handler has processed everything before the
+	// program exits in short-lived examples or CLI tools.
+	stats.Flush()
+}