package stackdriver

Import Path
	contrib.go.opencensus.io/exporter/stackdriver (on go.dev)

Dependency Relation
	imports 47 packages, and imported by 2 packages


Involved Source Files

	      label.go
	      metrics.go
	      metrics_batcher.go
	      metrics_proto.go
	      resource.go
	      sanitize.go
	
		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

		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.

	      stats.go
	      trace.go
	      trace_proto.go


Code Examples

	
		package main
		
		import (
			"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"
			"log"
			"net/http"
		)
		
		func main() {
			exporter, err := stackdriver.NewExporter(stackdriver.Options{ProjectID: "google-project-id"})
			if err != nil {
				log.Fatal(err)
			}
		
			// Export to Stackdriver Monitoring.
			if err = exporter.StartMetricsExporter(); err != nil {
				log.Fatal(err)
			}
		
			// Subscribe views to see stats in Stackdriver Monitoring.
			if err := view.Register(
				ochttp.ClientRoundtripLatencyDistribution,
				ochttp.ClientReceivedBytesDistribution,
			); 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.
		}


	
		package main
		
		import (
			"cloud.google.com/go/compute/metadata"
			"contrib.go.opencensus.io/exporter/stackdriver"
			"google.golang.org/genproto/googleapis/api/monitoredres"
			"log"
			"os"
		)
		
		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.
			if err = exporter.StartMetricsExporter(); err != nil {
				log.Fatal(err)
			}
		}




Package-Level Type Names (total 10, in which 3 are exported)


	/* sort exporteds by:  |  */
	
		Exporter is a stats and trace exporter that uploads data to Stackdriver.

		You can create a single Exporter and register it as both a trace exporter
		(to export to Stackdriver Trace) and a stats exporter (to integrate with
		Stackdriver Monitoring).

		
			
		
			
				ExportMetrics exports OpenCensus Metrics to Stackdriver Monitoring

			
				ExportMetricsProto exports OpenCensus Metrics Proto to Stackdriver Monitoring synchronously,
				without de-duping or adding proto metrics to the bundler.

			
				ExportSpan exports a SpanData to Stackdriver Trace.

			
				ExportView exports to the Stackdriver Monitoring if view data
				has one or more rows.
				Deprecated: use ExportMetrics and StartMetricsExporter instead.

			
				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.

			
				PushMetricsProto simliar with ExportMetricsProto but returns the number of dropped timeseries.

			
				PushTraceSpans exports a bundle of OpenCensus Spans.
				Returns number of dropped spans.

			
				StartMetricsExporter starts exporter by creating an interval reader that reads metrics
				from all registered producers at set interval and exports them.
				Use StopMetricsExporter to stop exporting metrics.
				Previously, it required registering exporter to export stats collected by opencensus.
				   exporter := stackdriver.NewExporter(stackdriver.Option{})
				   view.RegisterExporter(exporter)
				Now, it requires to call StartMetricsExporter() to export stats and metrics collected by opencensus.
				   exporter := stackdriver.NewExporter(stackdriver.Option{})
				   exporter.StartMetricsExporter()
				   defer exporter.StopMetricsExporter()

				Both approach should not be used simultaenously. Otherwise it may result into unknown behavior.
				Previous approach continues to work as before but will not report newly define metrics such
				as gauges.

			
				StopMetricsExporter stops exporter from exporting metrics.

			
		
			*T : go.opencensus.io/metric/metricexport.Exporter
			*T : go.opencensus.io/stats/view.Exporter
			*T : go.opencensus.io/trace.Exporter
			*T : net/http.Flusher
		
			func NewExporter(o Options) (*Exporter, error)
			func golang.org/x/pkgsite/internal/dcensus.NewViewExporter(cfg *config.Config) (_ *Exporter, err error)
		
			


	
		Labels represents a set of Stackdriver Monitoring labels.

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

		
			


	
		Options contains options for configuring the exporter.

		
			
				BundleCountThreshold determines how many view data events or trace spans
				can be buffered before batch uploading them to the backend.
				Optional.

			
				BundleDelayThreshold determines the max amount of time
				the exporter can wait before uploading view data or trace spans to
				the backend.
				Optional.

			
				Context allows you 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.

				Do not set a timeout on this context. Instead, set the Timeout option.

				If unset, context.Background() will be used.

			
				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.

			
				DefaultTraceAttributes will be appended to every span that is exported to
				Stackdriver Trace.

			
				GetMetricDisplayName allows customizing the display name for the metric
				associated with the given view. By default it will be:
				  MetricPrefix + view.Name

			
				GetMetricPrefix allows customizing the metric prefix for the given metric name.
				If it is not set, MetricPrefix is used. If MetricPrefix is not set, it defaults to:
				  "custom.googleapis.com/opencensus/"

				See: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors#MetricDescriptor

			
				GetMetricType allows customizing the metric type for the given view.
				By default, it will be:
				  "custom.googleapis.com/opencensus/" + view.Name

				See: https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors#MetricDescriptor
				Depreacted. Use GetMetricPrefix instead.

			
				Location is the identifier of the GCP or AWS cloud region/zone in which
				the data for a resource is stored.
				If not set, it will default to the location provided by the metadata server.

				It will be used in the location label of a Stackdriver monitored resource
				if the resource does not inherently belong to a specific project, e.g.
				on-premise resource like k8s_container or generic_task.

			
				MapResource converts a OpenCensus resource to a Stackdriver monitored resource.

				If this field is unset, DefaultMapResource will be used which encodes a set of default
				conversions from auto-detected resources to well-known Stackdriver monitored resources.

			
				MetricPrefix overrides the prefix of a Stackdriver metric names.
				Optional. If unset defaults to "custom.googleapis.com/opencensus/".
				If GetMetricPrefix is non-nil, this option is ignored.

			
				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.

			
				MonitoringClientOptions are additional options to be passed
				to the underlying Stackdriver Monitoring API client.
				Optional.

			
				NumberOfWorkers sets the number of go rountines that send requests
				to Stackdriver Monitoring and Trace. The minimum number of workers is 1.

			
				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.

			
				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.

				It will be used in the project_id label of a Stackdriver monitored
				resource if the resource does not inherently belong to a specific
				project, e.g. on-premise resource like k8s_container or generic_task.

			
				ReportingInterval sets the interval between reporting metrics.
				If it is set to zero then default value is used.

			
				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.

			
				ResourceByDescriptor may be provided to supply monitored resource dynamically
				based on the metric Descriptor. Most users will not need to set this,
				but should instead set ResourceDetector.

				The MonitoredResource and ResourceDetector fields are ignored if this
				field is set to a non-nil value.

				The ResourceByDescriptor is called to derive monitored resources from
				metric.Descriptor and the label map associated with the time-series.
				If any label is used for the derived resource then it will be removed
				from the label map. The remaining labels in the map are returned to
				be used with the time-series.

				If the func set to this field does not return valid resource even for one
				time-series then it will result into an error for the entire CreateTimeSeries request
				which may contain more than one time-series.

			
				ResourceDetector provides a hook to discover arbitrary resource information.

				The translation function provided in MapResource must be able to conver the
				the resource information to a Stackdriver monitored resource.

				If this field is unset, resource type and tags will automatically be discovered through
				the OC_RESOURCE_TYPE and OC_RESOURCE_LABELS environment variables.

			
				SkipCMD enforces to skip all the CreateMetricDescriptor calls.
				These calls are important in order to configure the unit of the metrics,
				but in some cases all the exported metrics are builtin (unit is configured)
				or the unit is not important.

			
				Timeout for all API calls. If not set, defaults to 5 seconds.

			
				TraceClientOptions are additional options to be passed
				to the underlying Stackdriver Trace API client.
				Optional.

			
				TraceSpansBufferMaxBytes is the maximum size (in bytes) of spans that
				will be buffered in memory before being dropped.

				If unset, a default of 8MB will be used.

			
				Override the user agent value supplied to Monitoring APIs and included as an
				attribute in trace data.

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


	


Package-Level Functions (total 52, in which 2 are exported)


	
		DefaultMapResource implements default resource mapping for well-known resource types


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


	


Package-Level Variables (total 22, none are exported)

	


Package-Level Constants (total 36, none are exported)