Add derived gauge example. (#1110)

* Add derived gauge example.

* fix fmt error and unreachable code error.

* fix typos.

examples/derived_gauges/README.md

@@ -0,0 +1,348 @@
+# Derived Gauge Example
+
+Table of Contents
+=================
+- [Summary](#summary)
+- [Run the example](#run-the-example)
+- [How to use derived gauges?](#how-to-use-derived-gauges-)
+ * [Initialize Metric Registry](#initialize-metric-registry)
+ * [Create derived gauge metric](#create-derived-gauge-metric)
+ * [Create derived gauge entry](#create-derived-gauge-entry)
+ * [Implement derived gauge interface](#implement-derived-gauge-interface)
+ * [Complete Example](#complete-example)
+
+
+
+## Summary 
+[top](#Table-of-Contents)
+
+This example demonstrates the use of derived gauges. It is a simple interactive program of consumer
+and producer. User can input number of items to produce. Producer produces specified number of
+items. Consumer consumes randomly consumes 1-5 items in each attempt. It then sleeps randomly
+between 1-10 seconds before the next attempt.
+
+There are two metrics collected to monitor the queue.
+1. **queue_size**: It is an instantaneous queue size represented using derived gauge int64.
+1. **queue_seconds_since_processed_last**: It is the time elaspsed in seconds since the last time
+ when the queue was consumed. It is represented using derived gauge float64.
+This example shows how to use gauge metrics. The program records two gauges.
+
+These metrics are read when exporter scrapes them. In this example prometheus exporter is used to
+scrape the data. Metrics can be viewed at [http://localhost:9090/metrics](http://localhost:9090/metrics) once the program is running.
+
+Enter different value for number of items to queue and fetch the metrics using above url to see the variation in the metrics.
+
+## Run the example
+
+```
+$ go get go.opencensus.io/examples/derived_gauges/...
+```
+
+then:
+
+```
+$ go run $(go env GOPATH)/src/go.opencensus.io/examples/derived_gauges/derived_gauge.go
+```
+
+## How to use derived gauges?
+
+### Initialize Metric Registry
+Create a new metric registry for all your metrics.
+This step is a general step for any kind of metrics and not specific to gauges.
+Register newly created registry with global producer manager.
+
+[embedmd]:# (derived_gauge.go reg)
+```go
+r := metric.NewRegistry()
+metricproducer.GlobalManager().AddProducer(r)
+```
+
+
+### Create derived gauge metric
+Create a gauge metric. In this example we have two metrics.
+
+**queue_size**
+
+[embedmd]:# (derived_gauge.go size)
+```go
+queueSizeGauge, err := r.AddInt64DerivedGauge(
+ "queue_size",
+ metric.WithDescription("Instantaneous queue size"),
+ metric.WithUnit(metricdata.UnitDimensionless))
+if err != nil {
+ log.Fatalf("error creating queue size derived gauge, error %v\n", err)
+}
+```
+
+**queue_seconds_since_processed_last**
+
+[embedmd]:# (derived_gauge.go elapsed)
+```go
+elapsedSeconds, err := r.AddFloat64DerivedGauge(
+ "queue_seconds_since_processed_last",
+ metric.WithDescription("time elapsed since last time the queue was processed"),
+ metric.WithUnit(metricdata.UnitDimensionless))
+if err != nil {
+ log.Fatalf("error creating queue_seconds_since_processed_last derived gauge, error %v\n", err)
+}
+```
+
+### Create derived gauge entry
+Now, create or insert a unique entry an interface `ToInt64` for a given set of tags. Since we are not using any tags in this example we only insert one entry for each derived gauge metric.
+
+**insert interface for queue_size**
+
+[embedmd]:# (derived_gauge.go entrySize)
+```go
+err = queueSizeGauge.UpsertEntry(q.Size)
+if err != nil {
+ log.Fatalf("error getting queue size derived gauge entry, error %v\n", err)
+}
+```
+
+**insert interface for queue_seconds_since_processed_lasto**
+
+[embedmd]:# (derived_gauge.go entryElapsed)
+```go
+err = elapsedSeconds.UpsertEntry(q.Elapsed)
+if err != nil {
+ log.Fatalf("error getting queue_seconds_since_processed_last derived gauge entry, error %v\n", err)
+}
+```
+
+
+### Implement derived gauge interface
+In order for metrics reader to read the value of your dervied gauge it must
+implement ToFloat64 or ToInt64
+
+[embedmd]:# (derived_gauge.go toint64)
+```go
+func (q *queue) Size() int64 {
+ q.mu.Lock()
+ defer q.mu.Unlock()
+ return int64(q.size)
+}
+
+```
+
+[embedmd]:# (derived_gauge.go tofloat64)
+```go
+func (q *queue) Elapsed() float64 {
+ q.mu.Lock()
+ defer q.mu.Unlock()
+ return time.Now().Sub(q.lastConsumed).Seconds()
+}
+
+```
+
+
+### Complete Example
+
+[embedmd]:# (derived_gauge.go entire)
+```go
+package main
+
+import (
+ "fmt"
+ "log"
+ "math/rand"
+ "sync"
+ "time"
+
+ "bufio"
+ "go.opencensus.io/exporter/prometheus"
+ "go.opencensus.io/metric"
+ "go.opencensus.io/metric/metricdata"
+ "go.opencensus.io/metric/metricproducer"
+ "net/http"
+ "os"
+ "strconv"
+ "strings"
+)
+
+// This example demonstrates the use of derived gauges. It is a simple interactive program of consumer
+// and producer. User can input number of items to produce. Producer produces specified number of
+// items. Consumer consumes randomly consumes 1-5 items in each attempt. It then sleeps randomly
+// between 1-10 seconds before the next attempt.
+//
+// There are two metrics collected to monitor the queue.
+// 1. queue_size: It is an instantaneous queue size represented using derived gauge int64.
+// 2. queue_seconds_since_processed_last: It is the time elaspsed in seconds since the last time
+// when the queue was consumed. It is represented using derived gauge float64.
+type queue struct {
+ size int
+ q []int
+ lastConsumed time.Time
+ mu sync.Mutex
+}
+
+var q = &queue{}
+
+const (
+ maxItemsToConsumePerAttempt = 25
+)
+
+func init() {
+ q.q = make([]int, 100)
+}
+
+// consume randomly dequeues upto 5 items from the queue
+func (q *queue) consume() {
+ q.mu.Lock()
+ defer q.mu.Unlock()
+
+ consumeCount := rand.Int() % maxItemsToConsumePerAttempt
+ i := 0
+ for i = 0; i < consumeCount; i++ {
+ if q.size > 0 {
+ q.q = q.q[1:]
+ q.size--
+ } else {
+ break
+ }
+ }
+ if i > 0 {
+ q.lastConsumed = time.Now()
+ }
+}
+
+// produce randomly enqueues upto 5 items from the queue
+func (q *queue) produce(count int) {
+ q.mu.Lock()
+ defer q.mu.Unlock()
+
+ for i := 0; i < count; i++ {
+ v := rand.Int() % 100
+ q.q = append(q.q, v)
+ q.size++
+ }
+ fmt.Printf("queued %d items, queue size is %d\n", count, q.size)
+}
+
+func (q *queue) runConsumer(interval int, cQuit chan bool) {
+ t := time.NewTicker(time.Duration(interval) * time.Second)
+ for {
+ select {
+ case <-t.C:
+ q.consume()
+ case <-cQuit:
+ t.Stop()
+ return
+ }
+ }
+}
+
+// Size reports instantaneous queue size.
+// This is the interface supplied while creating an entry for derived gauge int64.
+func (q *queue) Size() int64 {
+ q.mu.Lock()
+ defer q.mu.Unlock()
+ return int64(q.size)
+}
+
+
+// Elapsed reports time elapsed since the last time an item was consumed from the queue.
+// This is the interface supplied while creating an entry for derived gauge float64.
+func (q *queue) Elapsed() float64 {
+ q.mu.Lock()
+ defer q.mu.Unlock()
+ return time.Now().Sub(q.lastConsumed).Seconds()
+}
+
+
+func getInput() int {
+ reader := bufio.NewReader(os.Stdin)
+ limit := 100
+ for {
+ fmt.Printf("Enter number of items to put in consumer queue? [1-%d]: ", limit)
+ text, _ := reader.ReadString('\n')
+ count, err := strconv.Atoi(strings.TrimSuffix(text, "\n"))
+ if err == nil {
+ if count < 1 || count > limit {
+ fmt.Printf("invalid value %s\n", text)
+ continue
+ }
+ return count
+ }
+ fmt.Printf("error %v\n", err)
+ }
+}
+
+func doWork() {
+ fmt.Printf("Program monitors queue using two derived gauge metrics.\n")
+ fmt.Printf(" 1. queue_size = the instantaneous size of the queue.\n")
+ fmt.Printf(" 2. queue_seconds_since_processed_last = the number of seconds elapsed since last time the queue was processed.\n")
+ fmt.Printf("Go to http://localhost:9090/metrics to see the metrics.\n\n\n")
+
+ // Take a number of items to queue as an input from the user
+ // and enqueue the same number of items on to the consumer queue.
+ for {
+ count := getInput()
+ q.produce(count)
+ fmt.Printf("press CTRL+C to terminate the program\n")
+ }
+}
+
+func createAndStartExporter() {
+ // Create Prometheus metrics exporter to verify derived gauge metrics in this example.
+ exporter, err := prometheus.NewExporter(prometheus.Options{})
+ if err != nil {
+ log.Fatalf("Failed to create the prometheus metrics exporter: %v", err)
+ }
+ http.Handle("/metrics", exporter)
+ go func() {
+ log.Fatal(http.ListenAndServe(":9090", nil))
+
+ }()
+}
+
+func main() {
+ createAndStartExporter()
+
+ // Create metric registry and register it with global producer manager.
+ r := metric.NewRegistry()
+ metricproducer.GlobalManager().AddProducer(r)
+
+ // Create Int64DerviedGauge
+ queueSizeGauge, err := r.AddInt64DerivedGauge(
+ "queue_size",
+ metric.WithDescription("Instantaneous queue size"),
+ metric.WithUnit(metricdata.UnitDimensionless))
+ if err != nil {
+ log.Fatalf("error creating queue size derived gauge, error %v\n", err)
+ }
+
+ err = queueSizeGauge.UpsertEntry(q.Size)
+ if err != nil {
+ log.Fatalf("error getting queue size derived gauge entry, error %v\n", err)
+ }
+
+ // Create Float64DerviedGauge
+ elapsedSeconds, err := r.AddFloat64DerivedGauge(
+ "queue_seconds_since_processed_last",
+ metric.WithDescription("time elapsed since last time the queue was processed"),
+ metric.WithUnit(metricdata.UnitDimensionless))
+ if err != nil {
+ log.Fatalf("error creating queue_seconds_since_processed_last derived gauge, error %v\n", err)
+ }
+
+ err = elapsedSeconds.UpsertEntry(q.Elapsed)
+ if err != nil {
+ log.Fatalf("error getting queue_seconds_since_processed_last derived gauge entry, error %v\n", err)
+ }
+
+ cQuit := make(chan bool)
+ defer func() {
+ cQuit <- true
+ close(cQuit)
+ }()
+
+ // Run consumer and producer
+ go q.runConsumer(5, cQuit)
+
+ for {
+ doWork()
+ }
+}
+
+```