.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools@v0.0.0-20201105173854-bc9fc8d8c4bc/internal/event/export/ocagent/README.md

   1 # Exporting Metrics and Traces with OpenCensus, Zipkin, and Prometheus
   2
   3 This tutorial provides a minimum example to verify that metrics and traces
   4 can be exported to OpenCensus from Go tools.
   5
   6 ## Setting up oragent
   7
   8 1. Ensure you have [docker](https://www.docker.com/get-started) and [docker-compose](https://docs.docker.com/compose/install/).
   9 2. Clone [oragent](https://github.com/orijtech/oragent).
  10 3. In the oragent directory, start the services:
  11 ```bash
  12 docker-compose up
  13 ```
  14 If everything goes well, you should see output resembling the following:
  15 ```
  16 Starting oragent_zipkin_1 ... done
  17 Starting oragent_oragent_1 ... done
  18 Starting oragent_prometheus_1 ... done
  19 ...
  20 ```
  21 * You can check the status of the OpenCensus agent using zPages at http://localhost:55679/debug/tracez.
  22 * You can now access the Prometheus UI at http://localhost:9445.
  23 * You can now access the Zipkin UI at http://localhost:9444.
  24 4. To shut down oragent, hit Ctrl+C in the terminal.
  25 5. You can also start oragent in detached mode by running `docker-compose up -d`. To stop oragent while detached, run `docker-compose down`.
  26
  27 ## Exporting Metrics and Traces
  28 1. Clone the [tools](https://golang.org/x/tools) subrepository.
  29 1. Inside `internal`, create a file named `main.go` with the following contents:
  30 ```go
  31 package main
  32
  33 import (
  34         "context"
  35         "fmt"
  36         "math/rand"
  37         "net/http"
  38         "time"
  39
  40         "golang.org/x/tools/internal/event"
  41         "golang.org/x/tools/internal/event/export"
  42         "golang.org/x/tools/internal/event/export/metric"
  43         "golang.org/x/tools/internal/event/export/ocagent"
  44 )
  45
  46 type testExporter struct {
  47         metrics metric.Exporter
  48         ocagent *ocagent.Exporter
  49 }
  50
  51 func (e *testExporter) ProcessEvent(ctx context.Context, ev event.Event) (context.Context, event.Event) {
  52         ctx, ev = export.Tag(ctx, ev)
  53         ctx, ev = export.ContextSpan(ctx, ev)
  54         ctx, ev = e.metrics.ProcessEvent(ctx, ev)
  55         ctx, ev = e.ocagent.ProcessEvent(ctx, ev)
  56         return ctx, ev
  57 }
  58
  59 func main() {
  60         exporter := &testExporter{}
  61
  62         exporter.ocagent = ocagent.Connect(&ocagent.Config{
  63                 Start:   time.Now(),
  64                 Address: "http://127.0.0.1:55678",
  65                 Service: "go-tools-test",
  66                 Rate:    5 * time.Second,
  67                 Client:  &http.Client{},
  68         })
  69         event.SetExporter(exporter)
  70
  71         ctx := context.TODO()
  72         mLatency := event.NewFloat64Key("latency", "the latency in milliseconds")
  73         distribution := metric.HistogramFloat64Data{
  74                 Info: &metric.HistogramFloat64{
  75                         Name:        "latencyDistribution",
  76                         Description: "the various latencies",
  77                         Buckets:     []float64{0, 10, 50, 100, 200, 400, 800, 1000, 1400, 2000, 5000, 10000, 15000},
  78                 },
  79         }
  80
  81         distribution.Info.Record(&exporter.metrics, mLatency)
  82
  83         for {
  84                 sleep := randomSleep()
  85                 _, end := event.StartSpan(ctx, "main.randomSleep()")
  86                 time.Sleep(time.Duration(sleep) * time.Millisecond)
  87                 end()
  88                 event.Record(ctx, mLatency.Of(float64(sleep)))
  89
  90                 fmt.Println("Latency: ", float64(sleep))
  91         }
  92 }
  93
  94 func randomSleep() int64 {
  95         var max int64
  96         switch modulus := time.Now().Unix() % 5; modulus {
  97         case 0:
  98                 max = 17001
  99         case 1:
 100                 max = 8007
 101         case 2:
 102                 max = 917
 103         case 3:
 104                 max = 87
 105         case 4:
 106                 max = 1173
 107         }
 108         return rand.Int63n(max)
 109 }
 110
 111 ```
 112 3. Run the new file from within the tools repository:
 113 ```bash
 114 go run internal/main.go
 115 ```
 116 4. After about 5 seconds, OpenCensus should start receiving your new metrics, which you can see at http://localhost:8844/metrics. This page will look similar to the following:
 117 ```
 118 # HELP promdemo_latencyDistribution the various latencies
 119 # TYPE promdemo_latencyDistribution histogram
 120 promdemo_latencyDistribution_bucket{vendor="otc",le="0"} 0
 121 promdemo_latencyDistribution_bucket{vendor="otc",le="10"} 2
 122 promdemo_latencyDistribution_bucket{vendor="otc",le="50"} 9
 123 promdemo_latencyDistribution_bucket{vendor="otc",le="100"} 22
 124 promdemo_latencyDistribution_bucket{vendor="otc",le="200"} 35
 125 promdemo_latencyDistribution_bucket{vendor="otc",le="400"} 49
 126 promdemo_latencyDistribution_bucket{vendor="otc",le="800"} 63
 127 promdemo_latencyDistribution_bucket{vendor="otc",le="1000"} 78
 128 promdemo_latencyDistribution_bucket{vendor="otc",le="1400"} 93
 129 promdemo_latencyDistribution_bucket{vendor="otc",le="2000"} 108
 130 promdemo_latencyDistribution_bucket{vendor="otc",le="5000"} 123
 131 promdemo_latencyDistribution_bucket{vendor="otc",le="10000"} 138
 132 promdemo_latencyDistribution_bucket{vendor="otc",le="15000"} 153
 133 promdemo_latencyDistribution_bucket{vendor="otc",le="+Inf"} 15
 134 promdemo_latencyDistribution_sum{vendor="otc"} 1641
 135 promdemo_latencyDistribution_count{vendor="otc"} 15
 136 ```
 137 5. After a few more seconds, Prometheus should start displaying your new metrics. You can view the distribution at http://localhost:9445/graph?g0.range_input=5m&g0.stacked=1&g0.expr=rate(oragent_latencyDistribution_bucket%5B5m%5D)&g0.tab=0.
 138
 139 6. Zipkin should also start displaying traces. You can view them at http://localhost:9444/zipkin/?limit=10&lookback=300000&serviceName=go-tools-test.