Documentation

Overview

    Package observability sets up and configures observability tools.

    Package observability sets up and configures observability tools.

    Package observability sets up and configures observability tools.

    Package observability sets up and configures observability tools.

    Index

    Constants

    View Source
    const OCSQLDriverName = "ocsql"

      OCSQLDriverName is the name of the SQL driver wrapped by OpenCensus instrumentation code.

      Variables

      View Source
      var (
      	// BlameTagKey indicating Who to blame for the API request failure.
      	// NONE: no failure
      	// CLIENT: the client is at fault (e.g. invalid request)
      	// SERVER: the server is at fault
      	// EXTERNAL: some third party is at fault
      	// UNKNOWN: for everything else
      	BlameTagKey = tag.MustNewKey("blame")
      
      	// ResultTagKey contains a free format text describing the result of the
      	// request. Preferably ALL CAPS WITH UNDERSCORE.
      	// OK indicating a successful request.
      	// You can losely base this string on
      	// https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
      	// but feel free to use any text as long as it's easy to filter.
      	ResultTagKey = tag.MustNewKey("result")
      )
      View Source
      var (
      	// BlameNone indicate no API failure
      	BlameNone = tag.Upsert(BlameTagKey, "NONE")
      
      	// BlameClient indicate the client is at fault (e.g. invalid request)
      	BlameClient = tag.Upsert(BlameTagKey, "CLIENT")
      
      	// BlameServer indicate the server is at fault
      	BlameServer = tag.Upsert(BlameTagKey, "SERVER")
      
      	// BlameExternal indicate some third party is at fault
      	BlameExternal = tag.Upsert(BlameTagKey, "EXTERNAL")
      
      	// BlameUnknown can be used for everything else
      	BlameUnknown = tag.Upsert(BlameTagKey, "UNKNOWN")
      )
      View Source
      var (
      	// ResultOK add a tag indicating the API call is a success.
      	ResultOK = tag.Upsert(ResultTagKey, "OK")
      	// ResultNotOK add a tag indicating the API call is a failure.
      	ResultNotOK = ResultError("NOT_OK")
      )
      View Source
      var (
      	BuildIDTagKey  = tag.MustNewKey("build_id")
      	BuildTagTagKey = tag.MustNewKey("build_tag")
      
      	KnativeServiceTagKey       = tag.MustNewKey("k_service")
      	KnativeRevisionTagKey      = tag.MustNewKey("k_revision")
      	KnativeConfigurationTagKey = tag.MustNewKey("k_configuration")
      )

      Functions

      func AllViews

      func AllViews() []*view.View

        AllViews returns the collected OpenCensus views.

        func CollectViews

        func CollectViews(views ...*view.View)

          CollectViews collects all the OpenCensus views and register at a later time when we setup the metric exporter. This is mainly to be able to "register" the views in a module's init(), but still be able to handle the errors correctly. Typical usage: var v = view.View{...} func init() {

          observability.ColectViews(v)
          

          } // Actual view registration happens in exporter.StartExporter().

          func NewStackdriverMonitoredResource

          func NewStackdriverMonitoredResource(ctx context.Context, c *StackdriverConfig) monitoredresource.Interface

            NewStackdriverMonitoredResource returns a monitored resource with the required labels filled out. This needs to be the correct resource type so we can compared the default stackdriver metrics with the custom metrics we're generating.

            NOTE: This code is focused on support GCP Cloud Run Managed. If you are running in a different environment, you may see weird results.

            func RecordLatency

            func RecordLatency(ctx context.Context, start time.Time, m *stats.Float64Measure, mutators ...*tag.Mutator)

              RecordLatency calculate and record the latency. Usage example: func foo() {

              	 defer RecordLatency(&ctx, time.Now(), metric, tag1, tag2)
                // remaining of the function body.
              

              }

              func ResultError

              func ResultError(result string) tag.Mutator

                ResultError add a tag with the given string as the result.

                func WithBuildInfo

                func WithBuildInfo(ctx context.Context, info BuildInfo) context.Context

                  WithBuildInfo creates a new context with the build and revision info attached to the observability context.

                  Types

                  type BuildInfo

                  type BuildInfo interface {
                  	ID() string
                  	Tag() string
                  }

                    BuildInfo is the interface to provide build information.

                    type Config

                    type Config struct {
                    	ExporterType ExporterType `env:"OBSERVABILITY_EXPORTER, default=STACKDRIVER"`
                    
                    	OpenCensus  *OpenCensusConfig
                    	Stackdriver *StackdriverConfig
                    }

                      Config holds all of the configuration options for the observability exporter

                      type Exporter

                      type Exporter interface {
                      	io.Closer
                      	StartExporter(ctx context.Context) error
                      }

                        Exporter defines the minimum shared functionality for an observability exporter used by this application.

                        func NewFromEnv

                        func NewFromEnv(config *Config) (Exporter, error)

                          NewFromEnv returns the observability exporter given the provided configuration, or an error if it failed to be created.

                          func NewNoop

                          func NewNoop(_ context.Context) (Exporter, error)

                          func NewOpenCensus

                          func NewOpenCensus(ctx context.Context, config *OpenCensusConfig) (Exporter, error)

                            NewOpenCensus creates a new metrics and trace exporter for OpenCensus.

                            func NewStackdriver

                            func NewStackdriver(ctx context.Context, config *StackdriverConfig) (Exporter, error)

                              NewStackdriver creates a new metrics and trace exporter for Stackdriver.

                              type ExporterType

                              type ExporterType string

                                ExporterType represents a type of observability exporter.

                                const (
                                	ExporterStackdriver ExporterType = "STACKDRIVER"
                                	ExporterPrometheus  ExporterType = "PROMETHEUS"
                                	ExporterOCAgent     ExporterType = "OCAGENT"
                                	ExporterNoop        ExporterType = "NOOP"
                                )

                                type OpenCensusConfig

                                type OpenCensusConfig struct {
                                	SampleRate float64 `env:"TRACE_PROBABILITY, default=0.40"`
                                
                                	Insecure bool   `env:"OCAGENT_INSECURE"`
                                	Endpoint string `env:"OCAGENT_TRACE_EXPORTER_ENDPOINT"`
                                }

                                  OpenCensusConfig holds the configuration options for the open census exporter

                                  type StackdriverConfig

                                  type StackdriverConfig struct {
                                  	SampleRate float64 `env:"TRACE_PROBABILITY, default=0.40"`
                                  
                                  	ProjectID string `env:"PROJECT_ID, default=$GOOGLE_CLOUD_PROJECT"`
                                  
                                  	// Knative+Cloud Run container contract envvars:
                                  	//
                                  	// https://cloud.google.com/run/docs/reference/container-contract#env-vars
                                  	//
                                  	// If present, can be used to configured the Stackdriver MonitoredResource
                                  	// correctly.
                                  	Service   string `env:"K_SERVICE"`
                                  	Revision  string `env:"K_REVISION"`
                                  	Namespace string `env:"K_CONFIGURATION, default=en"`
                                  
                                  	// Allows for providing a real Google Cloud location when running locally for development.
                                  	// This is ignored if a real location was found during discovery.
                                  	LocationOverride string `env:"DEV_STACKDRIVER_LOCATION"`
                                  
                                  	// The following options are mostly for tuning the metrics reporting
                                  	// behavior. You normally should not change these values.
                                  	// ReportingInterval: should be >=60s as stackdriver enforces 60s minimal
                                  	// interval.
                                  	// BundleDelayThreshold / BundleCountThreshold: the stackdriver exporter
                                  	// uses https://google.golang.org/api/support/bundler, these two options
                                  	// control the max delay/count for batching the data points into one
                                  	// stackdriver request.
                                  	ReportingInterval    time.Duration `env:"STACKDRIVER_REPORTING_INTERVAL, default=2m"`
                                  	BundleDelayThreshold time.Duration `env:"STACKDRIVER_BUNDLE_DELAY_THRESHOLD, default=2s"`
                                  	BundleCountThreshold uint          `env:"STACKDRIVER_BUNDLE_COUNT_THRESHOLD, default=50"`
                                  	Timeout              time.Duration `env:"STACKDRIVER_TIMEOUT, default=1m"`
                                  
                                  	// The Cloud Run services are exporting many metrics that we get for free
                                  	// from the OpenCensus libaries. You can control whether to exclude some of
                                  	// them using the option below.
                                  	// Specify them using comma separated strings in envvar.
                                  	ExcludedMetricPrefixes []string `env:"STACKDRIVER_EXCLUDED_METRIC_PREFIXES"`
                                  }

                                    StackdriverConfig holds the configuration options for the stackdriver exporter