From df8e87c2cec0be3d26a0efac5384a4f6c49d6777 Mon Sep 17 00:00:00 2001 From: Nathan Dias Date: Fri, 22 Nov 2019 00:30:57 -0600 Subject: [PATCH] internal/telemetry/export/ocagent: add tutorial for exporting metrics This change adds a README that describes how to export metrics from Go tools to Prometheus via OpenCensus. Updates golang/go#33819 Change-Id: Ic417b539fd5ef95fee642321bd30997146cbedb3 Reviewed-on: https://go-review.googlesource.com/c/tools/+/208400 Reviewed-by: Emmanuel Odeke --- internal/telemetry/export/ocagent/README.md | 148 ++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 internal/telemetry/export/ocagent/README.md diff --git a/internal/telemetry/export/ocagent/README.md b/internal/telemetry/export/ocagent/README.md new file mode 100644 index 0000000000..a76f415158 --- /dev/null +++ b/internal/telemetry/export/ocagent/README.md @@ -0,0 +1,148 @@ +# Exporting Metrics with OpenCensus and Prometheus + +This tutorial provides a minimum example to verify that metrics can be exported to OpenCensus from Go tools. + +## Setting up the OpenCensus Agent +1. Follow the instructions for setting up the [OpenCensus Service](https://opencensus.io/agent). You will need to be able to run the agent. +2. Create a file named `config.yaml` with the following contents: +```yaml +exporters: + prometheus: + namespace: "promdemo" + address: "localhost:8888" + const_labels: { + "vendor": "gotools" + } +receivers: + opencensus: + address: "localhost:55678" + +``` +3. Run the OpenCensus Agent with the configuration file. The following command assumes that you are running from binary: +```bash +bin/ocagent_linux --config config.yaml +``` +4. If you see output similar to the following, the OpenCensus Agent is now running: +```bash +{"level":"info","ts":1574381470.1922305,"caller":"config/config.go:497","msg":"Metrics Exporter enabled","exporter":"prometheus"} +2019/11/21 18:11:11 Running OpenCensus Trace and Metrics receivers as a gRPC service at "localhost:55678" +2019/11/21 18:11:11 Running zPages on port 55679 +``` +5. You can check the status of the agent using zPages at http://localhost:55679/debug/tracez. + +## Setting up Prometheus +1. Follow the instructions for setting up [Prometheus](https://prometheus.io/docs/prometheus/latest/installation/). +2. Create a file named `prom.yaml` with the following contents: +```yaml +scrape_configs: + - job_name: 'agent1' + scrape_interval: 5s + static_configs: + - targets: ['localhost:8888'] +``` +3. Run Prometheus with the new configuration file. The following command assumes that you are running from pre-compiled binaries: +```bash +./prometheus --config.file=prom.yaml +``` +4. If you see output similar to the following, Prometheus is now running: +```bash +level=info ts=2019-11-22T00:27:13.772Z caller=main.go:626 msg="Server is ready to receive web requests." +``` +5. You can now access the Prometheus UI at http://localhost:9090. +6. Check to make sure Prometheus is able to scrape metrics from OpenCensus at http://localhost:9090/targets. If the state for the endpoint `http://localhost:8888/metrics` is not `UP`, make sure the OpenCensus agent is running. If you are running Prometheus using Docker, you may have to add `--net="host"` to your run command so that `localhost` resolves correctly. + +## Exporting Metrics +1. Clone the [tools](https://golang.org/x/tools) subrepository. +1. Inside `internal`, create a file named `main.go` with the following contents: +```go +package main + +import ( + "context" + "fmt" + "math/rand" + "net/http" + "time" + + "golang.org/x/tools/internal/telemetry/export" + "golang.org/x/tools/internal/telemetry/export/ocagent" + "golang.org/x/tools/internal/telemetry/metric" + "golang.org/x/tools/internal/telemetry/stats" +) + +func main() { + + exporter := ocagent.Connect(&ocagent.Config{ + Start: time.Now(), + Address: "http://127.0.0.1:55678", + Service: "go-tools-test", + Rate: 5 * time.Second, + Client: &http.Client{}, + }) + export.AddExporters(exporter) + + ctx := context.TODO() + mLatency := stats.Float64("latency", "the latency in milliseconds", "ms") + distribution := metric.HistogramFloat64Data{ + Info: &metric.HistogramFloat64{ + Name: "latencyDistribution", + Description: "the various latencies", + Buckets: []float64{0, 10, 50, 100, 200, 400, 800, 1000, 1400, 2000, 5000, 10000, 15000}, + }, + } + + distribution.Info.Record(mLatency) + + for { + sleep := randomSleep() + time.Sleep(time.Duration(sleep) * time.Millisecond) + mLatency.Record(ctx, float64(sleep)) + + fmt.Println("Latency: ", float64(sleep)) + } +} + +func randomSleep() int64 { + var max int64 + switch modulus := time.Now().Unix() % 5; modulus { + case 0: + max = 17001 + case 1: + max = 8007 + case 2: + max = 917 + case 3: + max = 87 + case 4: + max = 1173 + } + return rand.Int63n(max) +} + +``` +3. Run the new file from within the tools repository: +```bash +go run internal/main.go +``` +4. After about 5 seconds, OpenCensus should start receiving your new metrics, which you can see at http://localhost:8888/metrics. This page will look similar to the following: +``` +# HELP promdemo_latencyDistribution the various latencies +# TYPE promdemo_latencyDistribution histogram +promdemo_latencyDistribution_bucket{vendor="otc",le="0"} 0 +promdemo_latencyDistribution_bucket{vendor="otc",le="10"} 2 +promdemo_latencyDistribution_bucket{vendor="otc",le="50"} 9 +promdemo_latencyDistribution_bucket{vendor="otc",le="100"} 22 +promdemo_latencyDistribution_bucket{vendor="otc",le="200"} 35 +promdemo_latencyDistribution_bucket{vendor="otc",le="400"} 49 +promdemo_latencyDistribution_bucket{vendor="otc",le="800"} 63 +promdemo_latencyDistribution_bucket{vendor="otc",le="1000"} 78 +promdemo_latencyDistribution_bucket{vendor="otc",le="1400"} 93 +promdemo_latencyDistribution_bucket{vendor="otc",le="2000"} 108 +promdemo_latencyDistribution_bucket{vendor="otc",le="5000"} 123 +promdemo_latencyDistribution_bucket{vendor="otc",le="10000"} 138 +promdemo_latencyDistribution_bucket{vendor="otc",le="15000"} 153 +promdemo_latencyDistribution_bucket{vendor="otc",le="+Inf"} 15 +promdemo_latencyDistribution_sum{vendor="otc"} 1641 +promdemo_latencyDistribution_count{vendor="otc"} 15 +``` +5. After a few more seconds, Prometheus should start displaying your new metrics. You can view the distribution at http://localhost:9090/graph?g0.range_input=5m&g0.stacked=1&g0.expr=rate(promdemo_latencyDistribution_bucket%5B5m%5D)&g0.tab=0.