Allow customizing the set of default labels for stats exporting (#20)

* Introduce DefaultMonitoringLabels option
* Provide more documentation on how the exporter works with
  Stackdriver Monitoring concepts (labels, time series, resources).

Fixes: #16

Author: Ramon Nogueira

example_test.go

@@ -17,15 +17,18 @@ package stackdriver_test
 import (
 	"log"
 	"net/http"
+	"os"
 
+	"cloud.google.com/go/compute/metadata"
 	"contrib.go.opencensus.io/exporter/stackdriver"
 	"contrib.go.opencensus.io/exporter/stackdriver/propagation"
 	"go.opencensus.io/plugin/ochttp"
 	"go.opencensus.io/stats/view"
 	"go.opencensus.io/trace"
+	"google.golang.org/genproto/googleapis/api/monitoredres"
 )
 
-func Example() {
+func Example_defaults() {
 	exporter, err := stackdriver.NewExporter(stackdriver.Options{ProjectID: "google-project-id"})
 	if err != nil {
 		log.Fatal(err)
@@ -56,3 +59,51 @@ func Example() {
 	// All outgoing requests from client will include a Stackdriver Trace header.
 	// See the ochttp package for how to handle incoming requests.
 }
+
+func Example_gKE() {
+
+	// This example shows how to set up a Stackdriver exporter suitable for
+	// monitoring a GKE container.
+
+	instanceID, err := metadata.InstanceID()
+	if err != nil {
+		log.Println("Error getting instance ID:", err)
+		instanceID = "unknown"
+	}
+	zone, err := metadata.Zone()
+	if err != nil {
+		log.Println("Error getting zone:", err)
+		zone = "unknown"
+	}
+
+	exporter, err := stackdriver.NewExporter(stackdriver.Options{
+		ProjectID: "google-project-id",
+		// Set a MonitoredResource that represents a GKE container.
+		Resource: &monitoredres.MonitoredResource{
+			Type: "gke_container",
+			Labels: map[string]string{
+				"project_id":   "google-project-id",
+				"cluster_name": "my-cluster-name",
+				"instance_id":  instanceID,
+				"zone":         zone,
+
+				// See: https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/
+				"namespace_id":   os.Getenv("MY_POD_NAMESPACE"),
+				"pod_id":         os.Getenv("MY_POD_NAME"),
+				"container_name": os.Getenv("MY_CONTAINER_NAME"),
+			},
+		},
+		// Set DefaultMonitoringLabels to avoid getting the default "opencensus_task"
+		// label. For this to be valid, this exporter should be the only writer
+		// to the metrics against this gke_container MonitoredResource. In this case,
+		// it means you should only have one process writing to Stackdriver from this
+		// container.
+		DefaultMonitoringLabels: &stackdriver.Labels{},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Register so that views are exported.
+	view.RegisterExporter(exporter)
+}

label.go

@@ -0,0 +1,33 @@
+// 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 stackdriver
+
+// Labels represents a set of Stackdriver Monitoring labels.
+type Labels struct {
+	m map[string]labelValue
+}
+
+type labelValue struct {
+	val, desc string
+}
+
+// Set stores a label with the given key, value and description,
+// overwriting any previous values with the given key.
+func (labels *Labels) Set(key, value, description string) {
+	if labels.m == nil {
+		labels.m = make(map[string]labelValue)
+	}
+	labels.m[key] = labelValue{value, description}
+}

stackdriver.go

@@ -15,10 +15,37 @@
 // Package stackdriver contains the OpenCensus exporters for
 // Stackdriver Monitoring and Stackdriver Tracing.
 //
-// Please note that the Stackdriver exporter is currently experimental.
+// This exporter can be used to send metrics to Stackdriver Monitoring and traces
+// to Stackdriver trace.
 //
-// The package uses Application Default Credentials to authenticate.  See
-// https://developers.google.com/identity/protocols/application-default-credentials
+// The package uses Application Default Credentials to authenticate by default.
+// See: https://developers.google.com/identity/protocols/application-default-credentials
+//
+// Alternatively, pass the authentication options in both the MonitoringClientOptions
+// and the TraceClientOptions fields of Options.
+//
+// Stackdriver Monitoring
+//
+// This exporter support exporting OpenCensus views to Stackdriver Monitoring.
+// Each registered view becomes a metric in Stackdriver Monitoring, with the
+// tags becoming labels.
+//
+// The aggregation function determines the metric kind: LastValue aggregations
+// generate Gauge metrics and all other aggregations generate Cumulative metrics.
+//
+// In order to be able to push your stats to Stackdriver Monitoring, you must:
+//
+//   1. Create a Cloud project: https://support.google.com/cloud/answer/6251787?hl=en
+//   2. Enable billing: https://support.google.com/cloud/answer/6288653#new-billing
+//   3. Enable the Stackdriver Monitoring API: https://console.cloud.google.com/apis/dashboard
+//   4. Make sure you have a Premium Stackdriver account: https://cloud.google.com/monitoring/accounts/tiers
+//
+// These steps enable the API but don't require that your app is hosted on Google Cloud Platform.
+//
+// Stackdriver Trace
+//
+// This exporter supports exporting Trace Spans to Stackdriver Trace. It also
+// supports the Google "Cloud Trace" propagation format header.
 package stackdriver // import "contrib.go.opencensus.io/exporter/stackdriver"
 
 import (
@@ -71,19 +98,52 @@ type Options struct {
 	// Optional.
 	BundleCountThreshold int
 
-	// Resource is an optional field that represents the Stackdriver
-	// MonitoredResource, a resource that can be used for monitoring.
-	// If no custom ResourceDescriptor is set, a default MonitoredResource
-	// with type global and no resource labels will be used.
-	// Optional.
+	// Resource sets the MonitoredResource against which all views will be
+	// recorded by this exporter.
+	//
+	// All Stackdriver metrics created by this exporter are custom metrics,
+	// so only a limited number of MonitoredResource types are supported, see:
+	// https://cloud.google.com/monitoring/custom-metrics/creating-metrics#which-resource
+	//
+	// An important consideration when setting the Resource here is that
+	// Stackdriver Monitoring only allows a single writer per
+	// TimeSeries, see: https://cloud.google.com/monitoring/api/v3/metrics-details#intro-time-series
+	// A TimeSeries is uniquely defined by the metric type name
+	// (constructed from the view name and the MetricPrefix), the Resource field,
+	// and the set of label key/value pairs (in OpenCensus terminology: tag).
+	//
+	// If no custom Resource is set, a default MonitoredResource
+	// with type global and no resource labels will be used. If you explicitly
+	// set this field, you may also want to set custom DefaultMonitoringLabels.
+	//
+	// Optional, but encouraged.
 	Resource *monitoredrespb.MonitoredResource
 
-	// MetricPrefix overrides the OpenCensus prefix of a stackdriver metric.
-	// Optional.
+	// MetricPrefix overrides the prefix of a Stackdriver metric type names.
+	// Optional. If unset defaults to "OpenCensus".
 	MetricPrefix string
 
-	// DefaultTraceAttributes will be appended to every span that is exported.
+	// DefaultTraceAttributes will be appended to every span that is exported to
+	// Stackdriver Trace.
 	DefaultTraceAttributes map[string]interface{}
+
+	// DefaultMonitoringLabels are labels added to every metric created by this
+	// exporter in Stackdriver Monitoring.
+	//
+	// If unset, this defaults to a single label with key "opencensus_task" and
+	// value "go-<pid>@<hostname>". This default ensures that the set of labels
+	// together with the default Resource (global) are unique to this
+	// process, as required by Stackdriver Monitoring.
+	//
+	// If you set DefaultMonitoringLabels, make sure that the Resource field
+	// together with these labels is unique to the
+	// current process. This is to ensure that there is only a single writer to
+	// each TimeSeries in Stackdriver.
+	//
+	// Set this to &Labels{} (a pointer to an empty Labels) to avoid getting the
+	// default "opencensus_task" label. You should only do this if you know that
+	// the Resource you set uniquely identifies this Go process.
+	DefaultMonitoringLabels *Labels
 }
 
 // Exporter is a stats.Exporter and trace.Exporter
@@ -106,7 +166,7 @@ func NewExporter(o Options) (*Exporter, error) {
 		}
 		o.ProjectID = creds.ProjectID
 	}
-	se, err := newStatsExporter(o)
+	se, err := newStatsExporter(o, true)
 	if err != nil {
 		return nil, err
 	}