Documentation ¶
Overview ¶
Copyright 2018 Turbine Labs, Inc.
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.
Copyright 2018 Turbine Labs, Inc.
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 stats provides a standard Stats interface to a variety of underlying backends, along with a means to configure it from command line flags.
Index ¶
- Constants
- func CleanPrometheusStatName(s string) string
- func CleanPrometheusTagName(s string) string
- func DiagnosticsCallbackStats() []string
- func DiagnosticsCallbackTags() []string
- func Latency(s Stats, tags ...Tag) func()
- func LatencyWithSuccessRate(s Stats, tags ...Tag) func(error)
- func Matcher(expected Stats) gomock.Matcher
- func NewStatsDiagnosticsCallback(s Stats) executor.DiagnosticsCallback
- func PublishOnInterval(interval time.Duration, publishFn func()) error
- func SanitizeErrorType(err error) string
- func SuccessRate(s Stats, err error, tags ...Tag)
- func TagMatches(key, valueRegex string) gomock.Matcher
- type APIStatsOption
- type Field
- type FromFlags
- type LatchedHistogram
- type MockFromFlags
- type MockFromFlagsMockRecorder
- type MockStats
- func (m *MockStats) AddTags(tags ...Tag)
- func (m *MockStats) Close() error
- func (m *MockStats) Count(stat string, count float64, tags ...Tag)
- func (m *MockStats) EXPECT() *MockStatsMockRecorder
- func (m *MockStats) Event(stat string, fields ...Field)
- func (m *MockStats) Gauge(stat string, value float64, tags ...Tag)
- func (m *MockStats) Histogram(stat string, value float64, tags ...Tag)
- func (m *MockStats) Scope(scope string, scopes ...string) Stats
- func (m *MockStats) Timing(stat string, value time.Duration, tags ...Tag)
- type MockStatsMockRecorder
- func (mr *MockStatsMockRecorder) AddTags(tags ...interface{}) *gomock.Call
- func (mr *MockStatsMockRecorder) Close() *gomock.Call
- func (mr *MockStatsMockRecorder) Count(stat, count interface{}, tags ...interface{}) *gomock.Call
- func (mr *MockStatsMockRecorder) Event(stat interface{}, fields ...interface{}) *gomock.Call
- func (mr *MockStatsMockRecorder) Gauge(stat, value interface{}, tags ...interface{}) *gomock.Call
- func (mr *MockStatsMockRecorder) Histogram(stat, value interface{}, tags ...interface{}) *gomock.Call
- func (mr *MockStatsMockRecorder) Scope(scope interface{}, scopes ...interface{}) *gomock.Call
- func (mr *MockStatsMockRecorder) Timing(stat, value interface{}, tags ...interface{}) *gomock.Call
- type Option
- type Recorded
- type Stats
- func NewAPIStats(svc stats.StatsService) Stats
- func NewAsyncStats(s Stats) Stats
- func NewLatchingAPIStats(svc stats.StatsService, window time.Duration, baseValue float64, ...) Stats
- func NewMulti(statses ...Stats) Stats
- func NewNoopStats() Stats
- func NewRecordingStats(ch chan<- Recorded) Stats
- func NewRollUp(root Stats) Stats
- type Tag
Constants ¶
const ( LatencyStat = "latency" // latency timing RequestStat = "request" // request count SuccessStat = "success" // successful request count FailureStat = "failure" // failed request count ErrorTypeTag = "error_type" // error type tag name )
Stat names for Latency, SuccessRate, and LatencyWithSuccessRate.
const ( // DefaultLatchWindow specifies the default window over which stats are // aggregated. DefaultLatchWindow = 1 * time.Minute // DefaultHistogramNumBuckets specifies the number buckets used when aggregating // timing/histogram values. DefaultHistogramNumBuckets = 20 // DefaultHistogramBaseValue controls the upper bound of the lower bucket used // when aggregating timing/histogram values. DefaultHistogramBaseValue = 0.001 // 1 millisecond in fractional seconds // LatchedAtMetric is the name of the synthetic metric used to report when the // latch occurred. LatchedAtMetric = "latched_at" )
const ( StatusCodeTag = "status_code" StatusClassTag = "status_class" StatusClassSuccess = "success" StatusClassRedirect = "redirect" StatusClassClientErr = "client_error" StatusClassServerErr = "server_error" NodeTag = "node" ProxyTag = "proxy" ProxyVersionTag = "proxy-version" SourceTag = "source" TimestampTag = "timestamp" ZoneTag = "zone" )
const ( // DefaultClientApp is the clientApp used when constructing an api stats // client. If a specific clientApp is required, use SetStatsClientFromFlags. DefaultClientApp = "github.com/turbinelabs/stats" )
const MinimumStatsInterval = 1 * time.Second
MinimumStatsInterval is the minimum interval at which PublishOnInterval will publish stats.
Variables ¶
This section is empty.
Functions ¶
func CleanPrometheusStatName ¶
CleanPrometheusStatName strips characters which prometheus considers illegal from stat names. Stat names must match the regular expression: "[a-zA-Z_:][a-zA-Z0-9_:]*". Leading digits cause an underscore to be prepended to the name. All other illegal characters are converted to underscores.
func CleanPrometheusTagName ¶
CleanPrometheusTagName strips characters which prometheus considers illegal from tag names. Tag names must match the regular expression: "[a-zA-Z_][a-zA-Z0-9_]*". Leading digits cause an underscore to be prepended to the name. All other illegal characters are converted to underscores.
func DiagnosticsCallbackStats ¶
func DiagnosticsCallbackStats() []string
DiagnosticsCallbackStats returns a list of all possible stats generated.
func DiagnosticsCallbackTags ¶
func DiagnosticsCallbackTags() []string
DiagnosticsCallbackTags returns a list of all possible tags generated.
func Latency ¶
Latency measures the time between its invocation and the invocation of the function it returns. The timing is recorded as "latency" on the given Stats.
func LatencyWithSuccessRate ¶
LatencyWithSuccessRate combines Latency and SuccessRate. Like Latency, is measures time from its invocation until the returned function is invoked. The returned function uses its error parameter to distinguish between successful and failed requests.
func Matcher ¶
Matcher creates a gomock.Matcher for a Stats implementation generated by this package only. It does not work with arbitrary Stats implementations.
func NewStatsDiagnosticsCallback ¶
func NewStatsDiagnosticsCallback(s Stats) executor.DiagnosticsCallback
NewStatsDiagnosticsCallback wraps the given Stats within an implementation of executor.DiagnosticsCallback to records tasks started, tasks completed, task duration, attempts started, attempt delay, attempts completed, attempt duration, and callback duration.
func PublishOnInterval ¶
PublishOnInterval calls some function that will publish stats on a given interval. If the interval is less than MinimumStatsInterval an error is returned.
func SanitizeErrorType ¶
SanitizeErrorType converts an error's type into a format suitable for inclusion in a stats tag. Specifically it removes '*'.
func SuccessRate ¶
SuccessRate counts requests, successes, and failures. Each invocation counts a "request". If err is nil, a "success" is counted. If err is non-nil, a "failure" is counted with an "error_type" tag indicating the error's type.
func TagMatches ¶
TagMatches creates a Matcher that matches a Tag with the given key and a value regular expression.
Types ¶
type APIStatsOption ¶
type APIStatsOption func(*apiStatsFromFlags)
APIStatsOption is a configuration option the the API stats backend.
func AllowEmptyAPIKey ¶
func AllowEmptyAPIKey() APIStatsOption
AllowEmptyAPIKey configures the API StatsFromFlags to produce a NopStats in the case where no API key is specified
func SetLogger ¶
func SetLogger(logger *log.Logger) APIStatsOption
SetLogger specifies a custom Logger to use when constructing an stats.StatsService.
func SetStatsClientFromFlags ¶
func SetStatsClientFromFlags(statsClientFromFlags apiflags.StatsClientFromFlags) APIStatsOption
SetStatsClientFromFlags specifies a pre-configured apiflags.StatsClientFromFlags to use when creating a stats.StatsService.
func SetZoneFromFlags ¶
func SetZoneFromFlags(zoneFromFlags apiflags.ZoneFromFlags) APIStatsOption
SetZoneFromFlags specifies a pre-configured apiflags.ZoneFromFlags to use when creating an API stats sender.
type Field ¶
type Field struct { K string V interface{} }
A field is a more general variant of Tag. Instead of a string key and a string value, Tag supports an arbitrary interface for the value. Note that it is used when sending structured events, so the value should be serializable as JSON.
func FieldFromTag ¶
Creates a Field from a Tag object, preserving the key and value
func FieldsFromMap ¶
Creates an array of fields from a mop of strings to interface{}. Each Field in the new array will have a key in the format '<prefix>.<key from map>', with the value being the value from the supplied map
func FieldsFromTags ¶
Creates an array of Fields from an array of Tags
type FromFlags ¶
type FromFlags interface { // Validate validates the command line flags. Validate() error // Make constructs a Stats from command line flags. Make() (Stats, error) // Node returns the value of the node tag (must be called after Make). Node() string // Source returns the value of the source tag (must be called after Make). Source() string }
FromFlags produces a Stats from command line flags.
type LatchedHistogram ¶
type MockFromFlags ¶
type MockFromFlags struct {
// contains filtered or unexported fields
}
MockFromFlags is a mock of FromFlags interface
func NewMockFromFlags ¶
func NewMockFromFlags(ctrl *gomock.Controller) *MockFromFlags
NewMockFromFlags creates a new mock instance
func (*MockFromFlags) EXPECT ¶
func (m *MockFromFlags) EXPECT() *MockFromFlagsMockRecorder
EXPECT returns an object that allows the caller to indicate expected use
func (*MockFromFlags) Validate ¶
func (m *MockFromFlags) Validate() error
Validate mocks base method
type MockFromFlagsMockRecorder ¶
type MockFromFlagsMockRecorder struct {
// contains filtered or unexported fields
}
MockFromFlagsMockRecorder is the mock recorder for MockFromFlags
func (*MockFromFlagsMockRecorder) Make ¶
func (mr *MockFromFlagsMockRecorder) Make() *gomock.Call
Make indicates an expected call of Make
func (*MockFromFlagsMockRecorder) Node ¶
func (mr *MockFromFlagsMockRecorder) Node() *gomock.Call
Node indicates an expected call of Node
func (*MockFromFlagsMockRecorder) Source ¶
func (mr *MockFromFlagsMockRecorder) Source() *gomock.Call
Source indicates an expected call of Source
func (*MockFromFlagsMockRecorder) Validate ¶
func (mr *MockFromFlagsMockRecorder) Validate() *gomock.Call
Validate indicates an expected call of Validate
type MockStats ¶
type MockStats struct {
// contains filtered or unexported fields
}
MockStats is a mock of Stats interface
func NewMockStats ¶
func NewMockStats(ctrl *gomock.Controller) *MockStats
NewMockStats creates a new mock instance
func (*MockStats) EXPECT ¶
func (m *MockStats) EXPECT() *MockStatsMockRecorder
EXPECT returns an object that allows the caller to indicate expected use
type MockStatsMockRecorder ¶
type MockStatsMockRecorder struct {
// contains filtered or unexported fields
}
MockStatsMockRecorder is the mock recorder for MockStats
func (*MockStatsMockRecorder) AddTags ¶
func (mr *MockStatsMockRecorder) AddTags(tags ...interface{}) *gomock.Call
AddTags indicates an expected call of AddTags
func (*MockStatsMockRecorder) Close ¶
func (mr *MockStatsMockRecorder) Close() *gomock.Call
Close indicates an expected call of Close
func (*MockStatsMockRecorder) Count ¶
func (mr *MockStatsMockRecorder) Count(stat, count interface{}, tags ...interface{}) *gomock.Call
Count indicates an expected call of Count
func (*MockStatsMockRecorder) Event ¶
func (mr *MockStatsMockRecorder) Event(stat interface{}, fields ...interface{}) *gomock.Call
Event indicates an expected call of Event
func (*MockStatsMockRecorder) Gauge ¶
func (mr *MockStatsMockRecorder) Gauge(stat, value interface{}, tags ...interface{}) *gomock.Call
Gauge indicates an expected call of Gauge
func (*MockStatsMockRecorder) Histogram ¶
func (mr *MockStatsMockRecorder) Histogram(stat, value interface{}, tags ...interface{}) *gomock.Call
Histogram indicates an expected call of Histogram
func (*MockStatsMockRecorder) Scope ¶
func (mr *MockStatsMockRecorder) Scope(scope interface{}, scopes ...interface{}) *gomock.Call
Scope indicates an expected call of Scope
func (*MockStatsMockRecorder) Timing ¶
func (mr *MockStatsMockRecorder) Timing(stat, value interface{}, tags ...interface{}) *gomock.Call
Timing indicates an expected call of Timing
type Option ¶
type Option func(*fromFlagsOptions)
Option is an opaquely-typed option for NewFromFlags.
func APIStatsOptions ¶
func APIStatsOptions(opts ...APIStatsOption) Option
APIStatsOptions configures NewFromFlags to pass APIStatsOption values to the API Stats backend.
func DefaultBackends ¶
DefaultBackends configures NewFromFlags with default backends (that may be overridden by command line flags). Unknown backends are ignored.
func EnableAPIStatsBackend ¶
func EnableAPIStatsBackend() Option
EnableAPIStatsBackend enables the API stats backend.
type Recorded ¶
type Recorded struct { Method string Scope string Metric string Value float64 Timing time.Duration Tags []Tag }
Recorded represents a stats call recorded by a Stats object returned from NewRecordingStats.
type Stats ¶
type Stats interface { // Gauge measures the value of a particular thing at a particular time, // like the amount of fuel in a car’s gas tank or the number of users // connected to a system. Gauge(stat string, value float64, tags ...Tag) // Count tracks how many times something happened over a period, like // the number of database requests or page views. Count(stat string, count float64, tags ...Tag) // Histogram tracks the statistical distribution of a set of values, // like the duration of a number of database queries or the size of // files uploaded by users. The exact measurements tracked vary by // backend. For example, statsd will track the average, the minimum, // the maximum, the median, the 95th percentile, and the count. Histogram(stat string, value float64, tags ...Tag) // Timing measures the elapsed time. Timing(stat string, value time.Duration, tags ...Tag) // Event is used to record a named event, with a structured set of fields. // Not supported by all backends Event(stat string, fields ...Field) // AddTag adds a tag to the request client, this tag will be sent with all // subsequent stats queries, for backends that support tags. AddTags(tags ...Tag) // Scope creates a new Stats that appends the given scopes to // the prefix for each stat name. Scope(scope string, scopes ...string) Stats // Close should be called when the Stats is no longer needed Close() error }
Stats is an interface to an underlying stats backend. Tags are ignored for backends that do not support them.
func NewAPIStats ¶
func NewAPIStats(svc stats.StatsService) Stats
NewAPIStats creates a Stats that uses the given stats.StatsService to forward arbitrary stats with an unspecified source and zone. The source and zone may be subsequently overridden by invoking AddTags with tags named SourceTag and ZoneTag.
func NewAsyncStats ¶
NewAsyncStats creates a Stats implementation that forwards all measurement calls to an underlying Stats using goroutines. Scoped Stats instances created by this Stats will also be asynchronous.
func NewLatchingAPIStats ¶
func NewLatchingAPIStats( svc stats.StatsService, window time.Duration, baseValue float64, numBuckets int, ) Stats
NewLatchingAPIStats creates a Stats as in NewAPIStats, but with latching enabled.
func NewMulti ¶
NewMulti returns a Stats implementation that forwards calls to multiple Stats backends. Nil Stats values are ignored. If no non-nil Stats are passed, returns the result of NewNoopStats. If only a single non-nil Stats is passed, it is returned.
func NewNoopStats ¶
func NewNoopStats() Stats
NewNoopStats returns a Stats implementation that does nothing.
func NewRecordingStats ¶
NewRecordingStats returns a Stats implementation that records calls on the given channel.
func NewRollUp ¶
NewRollUp creates a Stats whose scopes delegate stats back to itself. For example,
h := NewRollUp(stats) scoped := h.Scope("x", "y", "z") scoped.Count("c", 1.0)
causes the following counters to be recorded: "c", "x.c", "x.y.c", and "x.y.z.c" (assuming a period is used as the scoped delimiter).
Source Files ¶
- api_sender.go
- api_stats.go
- cleaner.go
- console.go
- dogstatsd.go
- event_sender.go
- executor_diagnostics.go
- field.go
- fromflags.go
- helpers.go
- honeycomb.go
- latched_stat.go
- latching_sender.go
- latching_sender_fromflags.go
- matcher.go
- mock_fromflags.go
- mock_latching_sender.go
- mock_stats.go
- mock_stats_fromflags.go
- mock_xstats_sender.go
- multistats.go
- prometheus.go
- publisher.go
- stats.go
- stats_fromflags.go
- statsd.go
- tag.go
- tag_transform_parser.go
- tag_transformer.go
- wavefront.go
- wrappers.go
- xstats_sender.go