stackdriver

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2018 License: Apache-2.0 Imports: 34 Imported by: 0

README

OpenCensus Go Stackdriver

Build Status GoDoc

Provides OpenCensus exporter support for Stackdriver Monitoring and Stackdriver Trace.

Installation

$ go get -u contrib.go.opencensus.io/exporter/stackdriver

Documentation

Overview

Package stackdriver contains the OpenCensus exporters for Stackdriver Monitoring and Stackdriver Tracing.

This exporter can be used to send metrics to Stackdriver Monitoring and traces to Stackdriver trace.

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.

Example (Defaults) 
package main

import (
	"log"
	"net/http"

	"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"
)

func main() {
	exporter, err := stackdriver.NewExporter(stackdriver.Options{ProjectID: "google-project-id"})
	if err != nil {
		log.Fatal(err)
	}

	// Export to Stackdriver Monitoring.
	view.RegisterExporter(exporter)

	// Subscribe views to see stats in Stackdriver Monitoring.
	if err := view.Register(
		ochttp.ClientLatencyView,
		ochttp.ClientResponseBytesView,
	); err != nil {
		log.Fatal(err)
	}

	// Export to Stackdriver Trace.
	trace.RegisterExporter(exporter)

	// Automatically add a Stackdriver trace header to outgoing requests:
	client := &http.Client{
		Transport: &ochttp.Transport{
			Propagation: &propagation.HTTPFormat{},
		},
	}
	_ = client // use client

	// All outgoing requests from client will include a Stackdriver Trace header.
	// See the ochttp package for how to handle incoming requests.
}

Output:
Example (GKE) 
package main

import (
	"log"
	"os"

	"cloud.google.com/go/compute/metadata"
	"contrib.go.opencensus.io/exporter/stackdriver"
	"go.opencensus.io/stats/view"
	"google.golang.org/genproto/googleapis/api/monitoredres"
)

func main() {

	// 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)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Exporter 

type Exporter struct {
	// contains filtered or unexported fields
}

Exporter is a stats.Exporter and trace.Exporter implementation that uploads data to Stackdriver.

func NewExporter 

func NewExporter(o Options) (*Exporter, error)

NewExporter creates a new Exporter that implements both stats.Exporter and trace.Exporter.

func (*Exporter) ExportSpan 

func (e *Exporter) ExportSpan(sd *trace.SpanData)

ExportSpan exports a SpanData to Stackdriver Trace.

func (*Exporter) ExportView 

func (e *Exporter) ExportView(vd *view.Data)

ExportView exports to the Stackdriver Monitoring if view data has one or more rows.

func (*Exporter) Flush 

func (e *Exporter) Flush()

Flush waits for exported data to be uploaded.

This is useful if your program is ending and you do not want to lose recent stats or spans.

type Labels 

type Labels struct {
	// contains filtered or unexported fields
}

Labels represents a set of Stackdriver Monitoring labels.

func (*Labels) Set 

func (labels *Labels) Set(key, value, description string)

Set stores a label with the given key, value and description, overwriting any previous values with the given key.

type Options 

type Options struct {
	// ProjectID is the identifier of the Stackdriver
	// project the user is uploading the stats data to.
	// If not set, this will default to your "Application Default Credentials".
	// For details see: https://developers.google.com/accounts/docs/application-default-credentials
	ProjectID string

	// OnError is the hook to be called when there is
	// an error uploading the stats or tracing data.
	// If no custom hook is set, errors are logged.
	// Optional.
	OnError func(err error)

	// MonitoringClientOptions are additional options to be passed
	// to the underlying Stackdriver Monitoring API client.
	// Optional.
	MonitoringClientOptions []option.ClientOption

	// TraceClientOptions are additional options to be passed
	// to the underlying Stackdriver Trace API client.
	// Optional.
	TraceClientOptions []option.ClientOption

	// BundleDelayThreshold determines the max amount of time
	// the exporter can wait before uploading view data to
	// the backend.
	// Optional.
	BundleDelayThreshold time.Duration

	// BundleCountThreshold determines how many view data events
	// can be buffered before batch uploading them to the backend.
	// Optional.
	BundleCountThreshold int

	// 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.
	//
	// Deprecated: Use MonitoredResource instead.
	Resource *monitoredrespb.MonitoredResource

	// MonitoredResource 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 MonitoredResource 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 MonitoredResource field,
	// and the set of label key/value pairs (in OpenCensus terminology: tag).
	//
	// If no custom MonitoredResource is set AND if Resource is also not set then
	// 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.
	//
	// This field replaces Resource field. If this is set then it will override the
	// Resource field.
	// Optional, but encouraged.
	MonitoredResource monitoredresource.Interface

	// 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 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

	// Context allows users to provide a custom context for API calls.
	//
	// This context will be used several times: first, to create Stackdriver
	// trace and metric clients, and then every time a new batch of traces or
	// stats needs to be uploaded.
	//
	// If unset, context.Background() will be used.
	Context context.Context
}

Options contains options for configuring the exporter.

Source Files

View all Source files

Directories

Path Synopsis
examples
stats
Command stackdriver is an example program that collects data for video size.
 Command stackdriver is an example program that collects data for video size.
internal
testpb
Package testpb is a generated protocol buffer package.
 Package testpb is a generated protocol buffer package.
Package propagation implement X-Cloud-Trace-Context header propagation used by Google Cloud products.
 Package propagation implement X-Cloud-Trace-Context header propagation used by Google Cloud products.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.