Improve godoc for ochttp vars. (#444)

Also made tag keys agree with trace attributes.

Fixes: #423

Author: Ramon Nogueira

plugin/ochttp/client_test.go

@@ -34,6 +34,10 @@ func TestClient(t *testing.T) {
 	}))
 	defer server.Close()
 
+	for _, v := range ochttp.DefaultViews {
+		v.Subscribe()
+	}
+
 	views := []string{
 		"opencensus.io/http/client/requests",
 		"opencensus.io/http/client/latency",
@@ -46,7 +50,6 @@ func TestClient(t *testing.T) {
 			t.Errorf("view not found %q", name)
 			continue
 		}
-		v.Subscribe()
 	}
 
 	var (

plugin/ochttp/stats.go

@@ -15,113 +15,66 @@
 package ochttp
 
 import (
-	"fmt"
-
 	"go.opencensus.io/stats"
 	"go.opencensus.io/stats/view"
 	"go.opencensus.io/tag"
 )
 
+// The following client HTTP measures are supported for use in custom views:
 var (
-	// See: http://unitsofmeasure.org/ucum.html
-	unitByte          = "By"
-	unitDimensionless = "1"
-	unitMillisecond   = "ms"
+	ClientRequests, _         = stats.Int64("opencensus.io/http/client/requests", "Number of HTTP requests started", stats.UnitNone)
+	ClientRequestBodySize, _  = stats.Int64("opencensus.io/http/client/request_size", "HTTP request body size if set as ContentLength (uncompressed)", stats.UnitBytes)
+	ClientResponseBodySize, _ = stats.Int64("opencensus.io/http/client/response_size", "HTTP response body size (uncompressed)", stats.UnitBytes)
+	ClientLatency, _          = stats.Float64("opencensus.io/http/client/latency", "End-to-end latency", stats.UnitMilliseconds)
+)
 
-	bytesBucketBoundaries  = []float64{0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296}
-	millisBucketBoundaries = []float64{0, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000}
+// The following tags are applied to stats recorded by this package. Host, Path
+// and Method are applied to all measures. StatusCode is not applied to
+// ClientRequests, since it is recorded before the status is known.
+var (
+	// Host is the value of the HTTP Host header.
+	Host, _ = tag.NewKey("http.host")
+	// StatusCode is the numeric HTTP response status code,
+	// or "error" if a transport error occurred and no status code was read.
+	StatusCode, _ = tag.NewKey("http.status")
+	// Path is the URL path (not including query string) in the request.
+	Path, _ = tag.NewKey("http.path")
+	// Method is the HTTP method of the request, capitalized (GET, POST, etc.).
+	Method, _ = tag.NewKey("http.method")
+)
 
-	aggCount      = view.CountAggregation{}
-	aggDistBytes  = view.DistributionAggregation(bytesBucketBoundaries)
-	aggDistMillis = view.DistributionAggregation(millisBucketBoundaries)
+var (
+	DefaultSizeDistribution    = view.DistributionAggregation([]float64{0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296})
+	DefaultLatencyDistribution = view.DistributionAggregation([]float64{0, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000})
 )
 
+// Package ochttp provides some convenience views.
+// You need to subscribe to the views for data to actually be collected.
 var (
-	// ClientRequest is the number of client requests started.
-	ClientRequest = int64Measure("requests", "Number of HTTP requests started", unitDimensionless)
-	// ClientRequestBodySize is the size of request body if set as ContentLength (uncompressed bytes).
-	ClientRequestBodySize = int64Measure("request_size", "HTTP request body size (uncompressed)", unitByte)
-	// ClientResponseBodySize is the size of response body (uncompressed bytes).
-	ClientResponseBodySize = int64Measure("response_size", "HTTP response body size (uncompressed)", unitByte)
-	// ClientLatency is the end-to-end client latency (in milliseconds).
-	ClientLatency = floatMeasure("latency", "End-to-end latency", unitMillisecond)
+	ClientRequestCount, _                 = view.New("opencensus.io/http/client/requests", "Count of HTTP requests started", nil, ClientRequests, view.CountAggregation{})
+	ClientRequestBodySizeDistribution, _  = view.New("opencensus.io/http/client/request_size", "Size distribution of HTTP request body", nil, ClientRequestBodySize, DefaultSizeDistribution)
+	ClientResponseBodySizeDistribution, _ = view.New("opencensus.io/http/client/response_size", "Size distribution of HTTP response body", nil, ClientResponseBodySize, DefaultSizeDistribution)
+	ClientLatencyDistribution, _          = view.New("opencensus.io/http/client/latency", "Latency distribution of HTTP requests", nil, ClientLatency, DefaultLatencyDistribution)
 
-	// ClientRequestCount is a count of all instrumented HTTP requests.
-	ClientRequestCount = defaultView(ClientRequest, aggCount)
-	// ClientRequestBodySizeDistribution is a view of the size distribution of all instrumented request bodies.
-	ClientRequestBodySizeDistribution = defaultView(ClientRequestBodySize, aggDistBytes)
-	// ClientResponseBodySizeDistribution is a view of the size distribution of instrumented response bodies.
-	ClientResponseBodySizeDistribution = defaultView(ClientResponseBodySize, aggDistBytes)
-	// ClientLatencyDistribution is a view of the latency distribution of all instrumented requests.
-	ClientLatencyDistribution = defaultView(ClientLatency, aggDistMillis)
-	// ClientRequestCountByMethod is a view of response counts by HTTP method.
-	ClientRequestCountByMethod = mustView(view.New(
-		qualify("request_count_by_method"),
+	ClientRequestCountByMethod, _ = view.New(
+		"opencensus.io/http/client/request_count_by_method",
 		"Client request count by HTTP method",
 		[]tag.Key{Method},
-		ClientRequest,
-		aggCount))
-	// ClientResponseCountByStatusCode is a count of all instrumented HTTP responses HTTP status code.
-	ClientResponseCountByStatusCode = mustView(view.New(
-		qualify("response_count_by_status_code"),
+		ClientRequests,
+		view.CountAggregation{})
+	ClientResponseCountByStatusCode, _ = view.New(
+		"opencensus.io/http/client/response_count_by_status_code",
 		"Client response count by status code",
 		[]tag.Key{StatusCode},
 		ClientLatency,
-		aggCount))
-
-	// Host is the value of the HTTP Host header.
-	Host = key("host")
-	// StatusCode is the numeric HTTP response status code, or "error" if a transport error occurred and no status code
-	// was read.
-	StatusCode = key("status_code")
-	// Path is the URL path (not including query string) in the request.
-	Path = key("path")
-	// Method is the HTTP method of the request, capitalized (GET, POST, etc.).
-	Method = key("method")
-)
-
-func defaultView(m stats.Measure, agg view.Aggregation) *view.View {
-	v, err := view.New(m.Name(), m.Description(), nil, m, agg)
-	if err != nil {
-		panic(err)
-	}
-	if err := view.Register(v); err != nil {
-		panic(err)
-	}
-	return v
-}
-
-func key(name string) tag.Key {
-	k, err := tag.NewKey(qualify(name))
-	if err != nil {
-		panic(err)
-	}
-	return k
-}
+		view.CountAggregation{})
 
-func int64Measure(name, desc, unit string) *stats.Int64Measure {
-	m, err := stats.Int64(qualify(name), desc, unit)
-	if err != nil {
-		panic(err)
+	DefaultViews = []*view.View{
+		ClientRequestCount,
+		ClientRequestBodySizeDistribution,
+		ClientResponseBodySizeDistribution,
+		ClientLatencyDistribution,
+		ClientRequestCountByMethod,
+		ClientResponseCountByStatusCode,
 	}
-	return m
-}
-
-func floatMeasure(name, desc, unit string) *stats.Float64Measure {
-	m, err := stats.Float64(qualify(name), desc, unit)
-	if err != nil {
-		panic(err)
-	}
-	return m
-}
-
-func mustView(v *view.View, err error) *view.View {
-	if err != nil {
-		panic(err)
-	}
-	return v
-}
-
-func qualify(suffix string) string {
-	return fmt.Sprintf("opencensus.io/http/client/%s", suffix)
-}
+)

plugin/ochttp/stats_test.go

@@ -0,0 +1,27 @@
+package ochttp
+
+import (
+	"testing"
+
+	"go.opencensus.io/stats"
+	"go.opencensus.io/tag"
+)
+
+func TestVarsInitialized(t *testing.T) {
+	// Test that global initialization was successful
+	for i, k := range []tag.Key{Host, StatusCode, Path, Method} {
+		if k.Name() == "" {
+			t.Errorf("key not initialized: %d", i)
+		}
+	}
+	for i, m := range []stats.Measure{ClientRequests, ClientResponseBodySize, ClientRequestBodySize, ClientLatency} {
+		if m == nil {
+			t.Errorf("measure not initialized: %d", i)
+		}
+	}
+	for i, v := range DefaultViews {
+		if v == nil {
+			t.Errorf("view not initialized: %d", i)
+		}
+	}
+}

plugin/ochttp/stats_transport.go

@@ -48,7 +48,7 @@ func (t statsTransport) RoundTrip(req *http.Request) (*http.Response, error) {
 	} else if req.ContentLength > 0 {
 		track.reqSize = req.ContentLength
 	}
-	stats.Record(ctx, ClientRequest.M(1))
+	stats.Record(ctx, ClientRequests.M(1))
 
 	// Perform request.
 	resp, err := t.base.RoundTrip(req)

stats/units.go

@@ -0,0 +1,24 @@
+// Copyright 2018, OpenCensus Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package stats
+
+// Units are encoded according to the case-sensitive abbreviations from the
+// Unified Code for Units of Measure: http://unitsofmeasure.org/ucum.html
+const (
+	UnitNone         = "1"
+	UnitBytes        = "By"
+	UnitMilliseconds = "ms"
+)