golang.org/x/tools@v0.21.0/internal/event/export/ocagent/README.md (about)

     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.