signalfx

package module
v0.0.0-...-5a4be15 Latest Latest
Warning

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

 Go to latest Published: Mar 2, 2017 License: Apache-2.0 Imports: 16 Imported by: 2

README

go-signalfx

Circle CI Coverage Status GoDoc

Provides a simple way to send DataPoints to SignalFx

Fully documented via godoc.

Changes

This release greatly changes the API. It cleanly separates metrics and their data points; this change also extends to ownership semantics and goroutine cleanliness.

Separation of single data points and metric time series

Added Reporter.Inc, Reporter.Sample and Reporter.Record for one-shot counter, cumulative-counter and gauge values.

Metrics

Metrics are a new concept: they represent metric time series, which have internal state and may be converted to a data point at a particular point in time.

Client code may define its own metrics, however, convenient-to-use Counter, WrappedCounter, CumulativeCounter, WrappedCumulativeCounter, Gauge and WrappedGauge types are provided.

To track metrics over time, use Reporter.Track to start tracking them and Reporter.Untrack to stop tracking them.

No need for sfxproto

Client code should no longer need to know about the sfxproto library, which is used internally by signalfx.

Argument order

Function arguments should go from most general to most specific, e.g. from metric name, to dimensions, to value.

Simple usage

  1. Create a Config object. If $SFX_API_TOKEN is set in the environment, it will be used within the Config. Other default values are generally acceptable for most uses.

    config := signalfx.NewConfig()
config.AuthToken = "<YOUR_SIGNALFX_API_TOKEN>" // if $SFX_API_TOKEN is set, this is unnecessary

  2. Create a Reporter object and set any dimensions that should be set on every metric it sends to SignalFx. Optionally, call Reporter.SetPrefix to set a metric prefix which will be prepended to every metric that reporter reports (this can be used to enforce hard environment separation).

    reporter := signalfx.NewReporter(config, map[string]string{
    "dim0": "val0",
    "dim1": "val1",
})

  3. Add static DataPoints as needed, the value will be sent to SignalFx later when reporter.Report is called. All operations on the DataPoint are goroutine safe.

    reporter.Record(
                 "SomeGauge",
                 sfxproto.Dimensions{
                   "gauge_dim0": "gauge_val0",
                   "gauge_dim1": "gauge_val1",
                 },
                 5,
               )
// will be reported on Metric "SomeGauge" with integer value 5

  4. To track a metric over time, use a Metric:

    counter := NewCounter("counter-metric-name", nil, 0)
reporter.Track(counter)
⋮
counter.Inc(1)
⋮
counter.Inc(3)
Reporter.Report(…) // will report a counter value of 4

  5. Bucket is also provided to help with reporting multiple aspects of a Metric simultaneously. All operations on Bucket are goroutine safe.

    bucket := reporter.NewBucket("SomeBucket", nil)
bucket.Add(3)
bucket.Add(5)
// 5 DataPoints will be sent.
// * Metric "SomeBucket" value of 2 with appended dimension "rollup" = "count"
// * Metric "SomeBucket" value of 8 with appended dimension "rollup" = "sum"
// * Metric "SomeBucket" value of 34 with appended dimension "rollup" = "sumsquare"
// * Metric "SomeBucket.min" value of 3 with appended dimension "rollup" = "min"
// * Metric "SomeBucket.max" value of 5 with appended dimension "rollup" = "max"
// Min and Max are reset each time bucket is reported

  6. When ready to send the DataPoints to SignalFx, just Report them.

    reporter.Report(context.Background())

Documentation

Overview

Package signalfx provides several mechanisms to easily send datapoints to SignalFx

Users of this package will primarily interact with the Reporter type. Reporter is an object that tracks DataPoints and manages a Client.

For most cases, a reporter is created as follows (assuming $SFX_API_TOKEN is set in the environment) 

reporter := signalfx.Newreporter(signalfx.NewConfig(), nil)

DataPoints are created and tracked via various methods on Reporter like: 

inc, _ := reporter.NewInc("SomeIncrementer", nil)
inc.Inc(1)

And when ready to send the datapoints to SignalFx, just run 

_, err := reporter.Report(context.Background())

There are several types of metrics available, Gauge, Counter, CumulativeCounter and Bucket. Bucket is provided to track multiple aspects of a single metric such as number of times data has been added, the sum of each value added, the min and max values added, etc.

The value for Gauge, Counter and CumulativeCounter may be any type of int, float, string, nil or pointer or a Getter that returns one of those types. If val is a pointer type, its value should not be changed, when tracked by a Reporter, except within a PreReportCallback, for goroutine safety.

The Getter interface can also be used to as a value for a DataPoint. It may only return any kind of int, float, string, nil or a pointer to one of those types. Get will be called when Reporter.Report() is executed. Getters must implement their own goroutine safety with Get as required. There are a few types that implement Getter that can be used directly.

GetterFunc can wrap a function with the correct signature so that it satisfies the Getter interface: 

f := signalfx.GetterFunc(func() (interface{}, error) {
	return 5, nil
})
reporter.NewGauge("GetterFunc", f, nil)

Value can wrap the basic types (ints, floats, strings, nil and pointers to them) but is not goroutine safe. Changes should only be made in a PreReportCallback. 

i := 5
reporter.NewCounter("SomeCounter", signalfx.Value(&i), nil)
reporter.AddPreReportCallback(func() {
	i++
})

There are also Int32, Int64, Uint32 and Uint64 types available whose methods are goroutine safe and can also be safely changed if via atomic methods. 

val := signalfx.NewInt64(0)
counter := reporter.NewCounter("SomeOtherCounter", val, nil)
val.Inc(1)
atomic.AddInt64((*int64)(val), 1)

Index

Examples

Constants

View Source 
const (
	// BucketMetricCount represents the count of datapoints seen
	BucketMetricCount = iota
	// BucketMetricMin represents the smallest datapoint seen
	BucketMetricMin = iota
	// BucketMetricMax represents the largest datapoint seen
	BucketMetricMax = iota
	// BucketMetricSum represents the sum of all datapoints seen
	BucketMetricSum = iota
	// BucketMetricSumOfSquares represents the sum of squares of all datapoints seen
	BucketMetricSumOfSquares = iota
)
View Source 
const (
	// ClientVersion is the version of this package, sent as part of the default
	// user agent
	ClientVersion = "0.1.0"

	// DefaultMaxIdleConnections is the maximum idle (keep-alive) connections to
	// maintain with the signalfx server.
	DefaultMaxIdleConnections = 2

	// DefaultTimeoutDuration is the timeout used for connecting to the signalfx
	// server, including name resolution, as well as weaiting for headers
	DefaultTimeoutDuration = 60 * time.Second

	// DefaultURL is the URL used to send datapoints to signalfx
	DefaultURL = "https://ingest.signalfx.com/v2/datapoint"

	// DefaultUserAgent is the user agent sent to signalfx
	DefaultUserAgent = "go-signalfx/" + ClientVersion
)
View Source 
const (
	// TokenHeader is the header on which SignalFx looks for the api token
	TokenHeader = "X-SF-TOKEN"
)

Variables

View Source 
var (
	// ErrIllegalType is returned when trying to set the Datum value using an
	// unsupported type
	ErrIllegalType = fmt.Errorf("illegal value type")

	// ErrNoMetricName is returned when trying to create a DataPoint without a
	// Metric name
	ErrNoMetricName = fmt.Errorf("no metric name")
)

Functions

This section is empty.

Types

type Bucket 

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

A Bucket trakcs groups of values, reporting metrics as gauges and resetting each time it reports. All operations on Buckets are goroutine safe.

Example 
reporter := NewReporter(NewConfig(), map[string]string{
	"test_dimension0": "value0",
	"test_dimension1": "value1",
})

bucket := reporter.NewBucket("TestBucket", map[string]string{
	"test_bucket_dimension0": "bucket0",
	"test_bucket_dimension1": "bucket1",
})

bucket.Add(5)
bucket.Add(9)

fmt.Printf("Metric: %s\n", bucket.Metric())
fmt.Printf("Count: %d\n", bucket.Count())
fmt.Printf("Min: %d\n", bucket.Min())
fmt.Printf("Max: %d\n", bucket.Max())
fmt.Printf("Sum: %d\n", bucket.Sum())
fmt.Printf("SumOfSquares: %d\n", bucket.SumOfSquares())

dps, err := reporter.Report(context.Background())
if err != nil {
	fmt.Println("Error:", err)
} else {
	fmt.Println("Metrics:", len(dps))
}

Output:

Metric: TestBucket
Count: 2
Min: 5
Max: 9
Sum: 14
SumOfSquares: 106
Metrics: 5

func NewBucket 

func NewBucket(metric string, dimensions map[string]string) *Bucket

NewBucket creates a new Bucket. Because the passed in dimensions can not be locked by this method, it is important that the caller ensures its state does not change for the duration of the operation.

func (*Bucket) Add 

func (b *Bucket) Add(val int64)

Add an item to the Bucket, later reporting the result in the next report cycle.

func (*Bucket) Clone 

func (b *Bucket) Clone() *Bucket

Clone makes a deep copy of a Bucket

func (*Bucket) Count 

func (b *Bucket) Count() uint64

Count returns the number of items added to the Bucket

func (*Bucket) DataPoints 

func (b *Bucket) DataPoints() []DataPoint

DataPoints returns a DataPoints object with DataPoint values for Count, Sum, SumOfSquares, Min and Max (if set). Note that this resets all values. If no values have been added to the bucket since the last report, it returns 0 for count, sum and sum-of-squares, omitting max and min. If the count is higher than may be represented in an int64, then the count will be omitted.

func (*Bucket) Dimensions 

func (b *Bucket) Dimensions() map[string]string

Dimensions returns a copy of the dimensions of the Bucket. Changes are not reflected inside the Bucket itself.

func (*Bucket) Disable 

func (b *Bucket) Disable(metrics ...int)

Disable disables the given metrics for this bucket. They will be collected, but not reported.

func (*Bucket) Equal 

func (b *Bucket) Equal(r *Bucket) bool

Equal returns whether two buckets are exactly equal

func (*Bucket) Max 

func (b *Bucket) Max() int64

Max returns the highest item added to the Bucket

func (*Bucket) Metric 

func (b *Bucket) Metric() string

Metric returns the metric name of the Bucket

func (*Bucket) Min 

func (b *Bucket) Min() int64

Min returns the lowest item added to the Bucket

func (*Bucket) RemoveDimension 

func (b *Bucket) RemoveDimension(keys ...string)

RemoveDimension removes one or more dimensions with the given keys

func (*Bucket) SetDimension 

func (b *Bucket) SetDimension(key, value string)

SetDimension adds or overwrites the dimension at key with value. If the key or value is empty, no changes are made

func (*Bucket) SetDimensions 

func (b *Bucket) SetDimensions(dims map[string]string)

SetDimensions adds or overwrites multiple dimensions. Because the passed in dimensions can not be locked by this method, it is important that the caller ensures its state does not change for the duration of the operation.

func (*Bucket) SetMetric 

func (b *Bucket) SetMetric(name string)

SetMetric sets the metric name of the Bucket

func (*Bucket) Sum 

func (b *Bucket) Sum() int64

Sum returns the sum of all items added to the Bucket

func (*Bucket) SumOfSquares 

func (b *Bucket) SumOfSquares() int64

SumOfSquares returns the sum of the square of all items added to the Bucket

type Client 

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

A Client is used to send datapoints to SignalFx

func NewClient 

func NewClient(config *Config) *Client

NewClient returns a new Client. config is copied, so future changes to the external config object are not reflected within the client.

func (*Client) Submit 

func (c *Client) Submit(ctx context.Context, pdps *sfxproto.DataPoints) error

Submit forwards raw datapoints to SignalFx

type Config 

type Config struct {
	MaxIdleConnections    uint32
	TimeoutDuration       time.Duration
	URL                   string
	AuthToken             string
	UserAgent             string
	TLSInsecureSkipVerify bool
	Logger                io.Writer
}

Config is used to configure a Client. It should be created with New to have default values automatically set.

func NewConfig 

func NewConfig() *Config

NewConfig generates a new Config with default values. If $SFX_API_TOKEN is set in the environment, it will be used as the AuthToken.

func (*Config) Clone 

func (c *Config) Clone() *Config

Clone makes a deep copy of a Config

func (*Config) Transport 

func (c *Config) Transport() *http.Transport

Transport returns an http.Transport configured according to Config

type Counter 

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

A Counter represents a Counter metric (i.e., its internal value is reset to zero by its PostReportHook, although this should not be meaningful to client code).

func NewCounter 

func NewCounter(
	metric string,
	dimensions map[string]string,
	value uint64,
) *Counter

NewCounter returns a new Counter with the specified parameters. It does not copy the dimensions; client code should take care not to modify them in a goroutine-unsafe manner.

func (*Counter) DataPoint 

func (c *Counter) DataPoint() *DataPoint

DataPoint returns a DataPoint reflecting the Counter's internal state. It does not reset that state, leaving that to PostReportHook.

func (*Counter) Inc 

func (c *Counter) Inc(delta uint64) uint64

Inc increments a Counter's internal state. It is goroutine-safe.

func (*Counter) PostReportHook 

func (c *Counter) PostReportHook(v int64)

PostReportHook resets a Counter's internal state. It does this intelligently, by subtracting the successfully-reported value from the state (this way, the Counter may have been incremented in between the create of the reported DataPoint and the reset, and the state will be consistent). Calling PostReportHook with a negative value will result in a panic: counters may never take negative values.

In the normal case, PostReportHook should only be called by Reporter.Report. Its argument must always be the value of a DataPoint previously returned by Counter.DataPoint.

type CumulativeCounter 

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

A CumulativeCounter represents a cumulative counter, that is a counter whose internal state monotonically increases, and which never reports a value it has previously reported. It may be useful in order to track the value of counters over which one has no control.

func NewCumulativeCounter 

func NewCumulativeCounter(metric string, dimensions map[string]string, value uint64) *CumulativeCounter

NewCumulativeCounter returns a newly-created CumulativeCounter with the indicated initial state. It neither copies nor modifies the dimensions; client code should not modify dimensions in a goroutine-unsafe manner.

func (*CumulativeCounter) DataPoint 

func (cc *CumulativeCounter) DataPoint() *DataPoint

DataPoint returns a DataPoint reflecting the internal state of the CumulativeCounter. If that state has previously been successfully reported (as recorded by PostReportHook), it will simply return nil.

func (*CumulativeCounter) PostReportHook 

func (cc *CumulativeCounter) PostReportHook(v int64)

PostReportHook records a reported value of a CumulativeCounter. It will do the right thing if a yet-higher value has been reported in the interval since DataPoint was called. Calling PostReportHook with a negative value will result in a panic: counters may never take negative values.

In the normal case, PostReportHook should only be called by Reporter.Report. Its argument must always be the value of a DataPoint previously returned by CumulativeCounter.DataPoint.

func (*CumulativeCounter) Sample 

func (cc *CumulativeCounter) Sample(delta uint64)

Sample updates the CumulativeCounter's internal state.

type DataPoint 

type DataPoint struct {
	Metric     string
	Type       MetricType
	Value      int64
	Timestamp  time.Time
	Dimensions map[string]string
}

A DataPoint represents a single datum within a metric time series.

type DataPointCallback 

type DataPointCallback func() []DataPoint

DataPointCallback is a functional callback that can be passed to DataPointCallback as a way to have the caller calculate and return their own datapoints

type ErrContext 

type ErrContext error

ErrContext is returned when the context is canceled or times out

type ErrInvalidBody 

type ErrInvalidBody struct {
	Body string
}

ErrInvalidBody is returned when the signalfx response is anything other than "OK"

func (ErrInvalidBody) Error 

func (e ErrInvalidBody) Error() string

type ErrJSON 

type ErrJSON struct {
	Body []byte
}

ErrJSON is returned when there is an error parsing the signalfx JSON response

func (ErrJSON) Error 

func (e ErrJSON) Error() string

type ErrMarshal 

type ErrMarshal error

ErrMarshal is returned when there is an error marshaling the DataPoints

type ErrPost 

type ErrPost error

ErrPost is returned when there is an error posting data to signalfx

type ErrResponse 

type ErrResponse error

ErrResponse is returned when there is an error reading the signalfx response

type ErrStatus 

type ErrStatus struct {
	Body       []byte
	StatusCode int
}

ErrStatus is returned when the signalfx response code isn't 200

func (ErrStatus) Error 

func (e ErrStatus) Error() string

type Gauge 

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

A Gauge represents a metric which tracks a single value. This value may be positive or negative, and may increase or decrease over time. It neither copies nor modifies its dimension; client code should ensure that it does not modify them in a thread-unsafe manner. Unlike counters and cumulative counters, gauges are always reported.

func NewGauge 

func NewGauge(metric string, dimensions map[string]string, value int64) *Gauge

NewGauge returns a new Gauge with the indicated initial state.

func (*Gauge) DataPoint 

func (g *Gauge) DataPoint() *DataPoint

DataPoint returns a DataPoint reflecting the Gauge's internal state at the current point in time.

func (*Gauge) Record 

func (g *Gauge) Record(value int64)

Record sets a gauge's internal state to the indicated value.

type Getter 

type Getter interface {
	Get() (interface{}, error)
}

Getter is an interface that is used by DataPoint. Get must return any kind of int, float, nil or pointer to those types (a nil indicates an absent value). Any other type is invalid. It no longer supports strings.

func Value 

func Value(val interface{}) Getter

Value is a convenience function for making a value satisfy the Getter interface. val can be any type of int, float, nil or pointer to those types. If val is a pointer type, its value should not be changed, when in a Reporter, except within a PreReportCallback, for goroutine safety.

Example 
val := 5
cumulative := WrapCumulativeCounter("cumulative", nil, Value(&val))

val = 9
cdp := cumulative.DataPoint()
fmt.Println(cdp.Value)

Output:

9

type GetterFunc 

type GetterFunc func() (interface{}, error)

The GetterFunc type is an adapter to allow the use of ordinary functions as DataPoint Getters. If f is a function with the appropriate signature, GetterFunc(f) is a Getter object that calls f. f() must return a value that is any type of int, float, nil or pointer to those types.

Example 
val := 5
count := WrapGauge("count", nil, GetterFunc(func() (interface{}, error) {
	return val, nil
}))

val++
cdp := count.DataPoint()
fmt.Println(cdp.Value)

Output:

6

func (GetterFunc) Get 

func (f GetterFunc) Get() (interface{}, error)

Get calls f()

type GoMetrics 

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

GoMetrics gathers and reports generally useful go system stats for the reporter

func NewGoMetrics 

func NewGoMetrics(reporter *Reporter, dims map[string]string) *GoMetrics

NewGoMetrics registers the reporter to report go system metrics. You should provide enough dims to differentiate this set of metrics.

func (*GoMetrics) Close 

func (g *GoMetrics) Close() error

Close the metric source and will stop reporting these system stats to the reporter. Implements the io.Closer interface.

type HookedMetric 

type HookedMetric interface {
	Metric
	// PostReportHook is intended to only be called by
	// Reporter.Report.  Its argument should be the same as the
	// value of a DataPoint previously returned by
	// Metric.DataPoint; it should only be called once per such
	// DataPoint.  If it is called with any other value, results
	// are undefined (explicitly: PostReportHook may panic if
	// called with an invalid value).
	//
	// Clients of go-signalfx should not normally call
	// PostReportHook, unless it's doing something like
	// implementing its own reporting functionality.
	PostReportHook(reportedValue int64)
}

A HookedMetric has a PostReportHook method, which is called by Reporter.Report after successfully reporting a value. The intended use case is with Counters and CumulativeCounters, which need to reset some saved state once it's been reported, but it might be useful for other user-specified metric types.

type Int32 

type Int32 int32

Int32 satisfies the Getter interface using an atomic operation. Therefore it is safe to modify, when in a Reporter, outside the PreReportCallback as long as it is done so atomically.

func NewInt32 

func NewInt32(val int32) *Int32

NewInt32 returns a new Int32 set to val

func (*Int32) Get 

func (v *Int32) Get() (interface{}, error)

Get satisfies the Getter interface

func (*Int32) Inc 

func (v *Int32) Inc(delta int32) int32

Inc atomically adds delta to an Int32

func (*Int32) Set 

func (v *Int32) Set(val int32)

Set the value using an atomic operation

func (*Int32) Subtract 

func (v *Int32) Subtract(delta int64)

Subtract atomically subtracts delta from an Int32.

func (*Int32) Value 

func (v *Int32) Value() int32

Value atomically returns the value of an Int32

type Int64 

type Int64 int64

Int64 satisfies the Getter interface using an atomic operation. Therefore it is safe to modify, when in a Reporter, outside the PreReportCallback as long as it is done so atomically.

func NewInt64 

func NewInt64(val int64) *Int64

NewInt64 returns a new Int64 set to val

func (*Int64) Get 

func (v *Int64) Get() (interface{}, error)

Get satisfies the Getter interface

func (*Int64) Inc 

func (v *Int64) Inc(delta int64) int64

Inc atomically adds delta to an Int64

func (*Int64) Set 

func (v *Int64) Set(val int64)

Set the value using an atomic operation

func (*Int64) Subtract 

func (v *Int64) Subtract(delta int64)

Subtract atomically subtracts delta from an Int64.

func (*Int64) Value 

func (v *Int64) Value() int64

Value atomically returns the value of an Int64

type Metric 

type Metric interface {
	// DataPoint returns the value of the metric at the current
	// point in time.  If it has no value at the present point in
	// time, return nil.  A Reporter will add its metric prefix
	// and default dimensions to the metric and dimensions
	// indicated in the DataPoint.
	DataPoint() *DataPoint
}

A Metric represents a producer of datapoints (i.e., a metric time series). While individual datapoints are not goroutine-safe (they are owned by one goroutine at a time), metrics should be.

type MetricType 

type MetricType sfxproto.MetricType

MetricType exports sfxproto.MetricType to client code. 

const (
	CounterType           MetricType = MetricType(sfxproto.MetricType_COUNTER)
	CumulativeCounterType MetricType = MetricType(sfxproto.MetricType_CUMULATIVE_COUNTER)
	GaugeType             MetricType = MetricType(sfxproto.MetricType_GAUGE)
)

Only counters, cumulative counters and gauges are currently-supported metric types.

type Reporter 

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

Reporter is an object that tracks DataPoints and manages a Client. It is the recommended way to send data to SignalFX.

Example 
// auth token will be taken from $SFX_API_TOKEN if it exists
// for this example, it must be set correctly
reporter := NewReporter(NewConfig(), map[string]string{
	"test_dimension0": "value0",
	"test_dimension1": "value1",
})

gval := 0
gauge := WrapGauge(
	"TestGauge",
	map[string]string{
		"test_gauge_dimension0": "gauge0",
		"test_gauge_dimension1": "gauge1",
	},
	Value(&gval),
)
reporter.Track(gauge)

i := NewCounter(
	"TestInt64",
	map[string]string{
		"test_incrementer_dimension0": "incrementer0",
		"test_incrementer_dimension1": "incrementer1",
	},
	0,
)
reporter.Track(i)

cval := int64(0)
cumulative := WrapCumulativeCounter(
	"TestCumulative",
	map[string]string{
		"test_cumulative_dimension0": "cumulative0",
		"test_cumulative_dimension1": "cumulative1",
	},
	Value(&cval),
)
reporter.Track(cumulative)

atomic.AddInt64(&cval, 1)

reporter.AddPreReportCallback(func() {
	// modify these values safely within this callback
	// modification of pointer values otherwise is not goroutine safe
	gval = 7
})

// incrementers are goroutine safe
i.Inc(1)
i.Inc(5)

dps, err := reporter.Report(context.Background())
if err != nil {
	fmt.Printf("Error: %v\n", err)
} else {
	// find the associated datapoints for each metric
	var gval, ival, cval int64
	for _, dp := range dps {
		switch dp.Metric {
		case "TestGauge":
			gval = dp.Value
		case "TestInt64":
			ival = dp.Value
		case "TestCumulative":
			cval = dp.Value
		default:
			panic("this should never happen")
		}
	}
	fmt.Printf("Gauge: %d\n", gval)
	fmt.Printf("Incrementer: %d\n", ival)
	fmt.Printf("Cumulative: %d\n", cval)
	fmt.Printf("Metrics: %d\n", len(dps)) // FIXME: Fix this line…
}

Output:

Gauge: 7
Incrementer: 6
Cumulative: 1
Metrics: 3

func NewReporter 

func NewReporter(config *Config,
	defaultDimensions map[string]string) *Reporter

NewReporter returns a new Reporter object. Any dimensions supplied will be appended to all DataPoints sent to SignalFX. config is copied, so future changes to the external config object are not reflected within the reporter.

func (*Reporter) Add 

func (r *Reporter) Add(dp DataPoint)

Add adds a single DataPoint to a Reporter; it will be reported and, once successfully reported, deleted.

func (*Reporter) AddDataPointsCallback 

func (r *Reporter) AddDataPointsCallback(f DataPointCallback)

AddDataPointsCallback adds a callback that itself will generate datapoints to report/

func (*Reporter) AddPreReportCallback 

func (r *Reporter) AddPreReportCallback(f func())

AddPreReportCallback adds a function that is called before Report(). This is useful for refetching things like runtime.Memstats() so they are only fetched once per report() call. If a DataPoint

func (*Reporter) DeleteDimension 

func (r *Reporter) DeleteDimension(key string)

DeleteDimension deletes a default dimension.

func (*Reporter) Inc 

func (r *Reporter) Inc(metric string, dimensions map[string]string, delta uint64) error

Inc adds a one-shot data point for a counter with the indicated delta since the last report. If delta is greater than the maximum possible int64, Inc will panic.

func (*Reporter) NewBucket 

func (r *Reporter) NewBucket(metric string, dimensions map[string]string) *Bucket

NewBucket creates a new Bucket object that is tracked by the Reporter. Buckets are goroutine safe.

func (*Reporter) Record 

func (r *Reporter) Record(metric string, dimensions map[string]string, value int64) error

Record adds a one-shot data point for a gauge with the indicated value at this point in time.

func (*Reporter) RemoveBucket 

func (r *Reporter) RemoveBucket(bs ...*Bucket)

RemoveBucket takes Bucket(s) out of the set being tracked by the Reporter

func (*Reporter) Report 

func (r *Reporter) Report(ctx context.Context) ([]DataPoint, error)

Report sends all tracked DataPoints to SignalFX. PreReportCallbacks will be run before building the dataset to send. DataPoint callbacks will be executed and added to the dataset, but do not become tracked by the Reporter.

func (*Reporter) RunInBackground 

func (r *Reporter) RunInBackground(interval time.Duration) (cancel func())

RunInBackground starts a goroutine which calls Reporter.Report on the specified interval. It returns a function which may be used to cancel the backgrounding.

func (*Reporter) Sample 

func (r *Reporter) Sample(metric string, dimensions map[string]string, value uint64) error

Sample adds a one-shot data point for a cumulative counter with the indicated value at this point in time.

func (*Reporter) SetDimension 

func (r *Reporter) SetDimension(key, value string)

SetDimension sets a default dimension which will be reported for all data points.

func (*Reporter) SetPrefix 

func (r *Reporter) SetPrefix(prefix string)

SetPrefix sets a particular prefix for all metrics reported by this reporter.

func (*Reporter) Track 

func (r *Reporter) Track(m ...Metric)

Track adds a Metric to a Reporter's set of tracked Metrics. Its value will be reported once each time Report is called.

func (*Reporter) Untrack 

func (r *Reporter) Untrack(m ...Metric)

Untrack removes a Metric from a Reporter's set of tracked Metrics.

type StableGauge 

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

A StableGauge is the same as a Guage, but will not report the same value multiple times sequentially.

func NewStableGauge 

func NewStableGauge(metric string, dimensions map[string]string, value int64) *StableGauge

NewStableGauge returns a new StableGauge with the indicated initial state.

func (*StableGauge) DataPoint 

func (g *StableGauge) DataPoint() *DataPoint

DataPoint returns a DataPoint reflecting the StableGauge's internal state at the current point in time, if it differs since the last call.

func (*StableGauge) Record 

func (g *StableGauge) Record(value int64)

Record sets a gauge's internal state to the indicated value.

type Subtractor 

type Subtractor interface {
	Getter
	Subtract(int64)
}

A Subtractor is a Getter which is also subtractable.

type Uint32 

type Uint32 uint32

Uint32 satisfies the Getter interface using an atomic operation. Therefore it is safe to modify, when in a Reporter, outside the PreReportCallback as long as it is done so atomically.

func NewUint32 

func NewUint32(val int32) *Uint32

NewUint32 returns a new Uint32 set to val

func (*Uint32) Get 

func (v *Uint32) Get() (interface{}, error)

Get satisfies the Getter interface

func (*Uint32) Inc 

func (v *Uint32) Inc(delta uint32) uint32

Inc atomically adds delta to a Uint32

func (*Uint32) Set 

func (v *Uint32) Set(val uint32)

Set the value using an atomic operation

func (*Uint32) Subtract 

func (v *Uint32) Subtract(delta int64)

Subtract atomically subtracts delta from a Uint32

func (*Uint32) Value 

func (v *Uint32) Value() uint32

Value atomically returns the value of a Uint32

type Uint64 

type Uint64 uint64

Uint64 satisfies the Getter interface using an atomic operation. Therefore it is safe to modify, when in a Reporter, outside the PreReportCallback as long as it is done so atomically.

func NewUint64 

func NewUint64(val int64) *Uint64

NewUint64 returns a new Uint64 set to val

func (*Uint64) Get 

func (v *Uint64) Get() (interface{}, error)

Get satisfies the Getter interface

func (*Uint64) Inc 

func (v *Uint64) Inc(delta uint64) uint64

Inc atomically adds delta to a Uint64

func (*Uint64) Set 

func (v *Uint64) Set(val uint64)

Set the value using an atomic operation

func (*Uint64) Subtract 

func (v *Uint64) Subtract(delta int64)

Subtract atomically subtracts delta from a Uint32

func (*Uint64) Value 

func (v *Uint64) Value() uint64

Value atomically returns the value of a Uint64

type WrappedCounter 

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

A WrappedCounter wraps Subtractor—a type of Value which may be gotten from or subtracted from—in order to provide an easy-to-use way to monitor state elsewhere within an application. Of note to client code, this means that the wrapped counter's value will be reset after each successful report. Clients wishing to have a monotonically-increasing counter should instead use a WrappedCumulativeCounter.

func WrapCounter 

func WrapCounter(
	metric string,
	dimensions map[string]string,
	value Subtractor,
) *WrappedCounter

WrapCounter returns a WrappedCounter wrapping value.

func (*WrappedCounter) DataPoint 

func (c *WrappedCounter) DataPoint() *DataPoint

DataPoint returns a DataPoint representing the current state of the wrapped counter value. If that current state is negative or zero, then no DataPoint will be returned.

func (*WrappedCounter) PostReportHook 

func (c *WrappedCounter) PostReportHook(v int64)

PostReportHook resets a counter by subtracting the successfully-reported value from its internal state. Passing in a negative value will result in a panic, as a WrappedCounter's internal state may not be negative.

type WrappedCumulativeCounter 

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

A WrappedCumulativeCounter wraps a value elsewhere in memory. That value must monotonically increase.

func WrapCumulativeCounter 

func WrapCumulativeCounter(
	metric string,
	dimensions map[string]string,
	value Getter,
) *WrappedCumulativeCounter

WrapCumulativeCounter wraps a cumulative counter elsewhere in memory, returning a newly-allocated WrappedCumulativeCounter. Dimensions are neither copied nor modified; client code should take care not to modify them in a goroutine-unsafe manner.

func (*WrappedCumulativeCounter) DataPoint 

func (cc *WrappedCumulativeCounter) DataPoint() *DataPoint

DataPoint returns a DataPoint reflecting the internal state of the WrappedCumulativeCounter at a particular point in time. It will return nil of the counter's value or higher has been previously reported.

func (*WrappedCumulativeCounter) PostReportHook 

func (cc *WrappedCumulativeCounter) PostReportHook(v int64)

PostReportHook records that a particular value has been successfully reported. If that value is negative, it will panic, as cumulative counter values may never be negative. It is goroutine-safe.

type WrappedGauge 

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

A WrappedGauge wraps a Getter elsewhere in memory.

func WrapGauge 

func WrapGauge(
	metric string,
	dimensions map[string]string,
	value Getter,
) *WrappedGauge

WrapGauge wraps a value in memory. It neither copies nor updates its dimensions; client code should take care not to modify them in a goroutine-unsafe manner.

func (*WrappedGauge) DataPoint 

func (c *WrappedGauge) DataPoint() *DataPoint

DataPoint returns a DataPoint reflecting the current value of the WrappedGauge.

Source Files

View all Source files

Directories

Path Synopsis
examples
ad-hoc
readme
Package sfxproto is a generated protocol buffer package.
 Package sfxproto is a generated protocol buffer package.

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.