stats

package module
v0.0.0-...-eaffe4d Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2018 License: Apache-2.0 Imports: 35 Imported by: 4

README

turbinelabs/stats

This project is no longer maintained by Turbine Labs, which has shut down.

Apache 2.0 GoDoc CircleCI Go Report Card codecov

The stats project provides a standard Stats interface to a variety of underlying backends, along with a means to configure it from command line flags.

Requirements

  • Go 1.10.3 or later (previous versions may work, but we don't build or test against them)

Dependencies

The stats project depends on these packages:

The tests depend on our test package, and on gomock. It should always be safe to use HEAD of all master branches of Turbine Labs open source projects together, or to vendor them with the same git tag.

gomock-based MockStats and MockFromFlags are provided.

Additionally, we vendor github.com/rs/xstats. This should be considered an opaque implementation detail, see Vendoring for more discussion.

Install

go get -u github.com/turbinelabs/stats/...

Clone/Test

mkdir -p $GOPATH/src/turbinelabs
git clone https://github.com/turbinelabs/stats.git > $GOPATH/src/turbinelabs/stats
go test github.com/turbinelabs/stats/...

Godoc

stats

Versioning

Please see Versioning of Turbine Labs Open Source Projects.

Pull Requests

Patches accepted! Please see Contributing to Turbine Labs Open Source Projects.

Code of Conduct

All Turbine Labs open-sourced projects are released with a Contributor Code of Conduct. By participating in our projects you agree to abide by its terms, which will be carefully enforced.

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

View Source 
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.

View Source 
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"
)
View Source 
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"
)
View Source 
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"
)
View Source 
const MinimumStatsInterval = 1 * time.Second

MinimumStatsInterval is the minimum interval at which PublishOnInterval will publish stats.

Variables

This section is empty.

Functions

func CleanPrometheusStatName 

func CleanPrometheusStatName(s string) string

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 

func CleanPrometheusTagName(s string) string

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 

func Latency(s Stats, tags ...Tag) func()

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 

func LatencyWithSuccessRate(s Stats, tags ...Tag) func(error)

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 

func Matcher(expected Stats) gomock.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 

func PublishOnInterval(
	interval time.Duration,
	publishFn func(),
) error

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 

func SanitizeErrorType(err error) string

SanitizeErrorType converts an error's type into a format suitable for inclusion in a stats tag. Specifically it removes '*'.

func SuccessRate 

func SuccessRate(s Stats, err error, tags ...Tag)

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 

func TagMatches(key, valueRegex string) gomock.Matcher

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 

func FieldFromTag(tag Tag) Field

Creates a Field from a Tag object, preserving the key and value

func FieldsFromMap 

func FieldsFromMap(prefix string, m map[string]string) []Field

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 

func FieldsFromTags(tags []Tag) []Field

Creates an array of Fields from an array of Tags

func NewField 

func NewField(key string, val interface{}) Field

NewField produces a new tag from a string

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.

func NewFromFlags 

func NewFromFlags(fs tbnflag.FlagSet, options ...Option) FromFlags

NewFromFlags produces a FromFlags configured by the given flagset and options.

type LatchedHistogram 

type LatchedHistogram struct {
	BaseValue float64
	Buckets   []int64
	Count     int64
	Sum       float64
	Min       float64
	Max       float64
}

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

func (m *MockFromFlags) Make() (Stats, error)

Make mocks base method

func (*MockFromFlags) Node 

func (m *MockFromFlags) Node() string

Node mocks base method

func (*MockFromFlags) Source 

func (m *MockFromFlags) Source() string

Source mocks base method

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

func (m *MockStats) AddTags(tags ...Tag)

AddTags mocks base method

func (*MockStats) Close 

func (m *MockStats) Close() error

Close mocks base method

func (*MockStats) Count 

func (m *MockStats) Count(stat string, count float64, tags ...Tag)

Count mocks base method

func (*MockStats) EXPECT 

func (m *MockStats) EXPECT() *MockStatsMockRecorder

EXPECT returns an object that allows the caller to indicate expected use

func (*MockStats) Event 

func (m *MockStats) Event(stat string, fields ...Field)

Event mocks base method

func (*MockStats) Gauge 

func (m *MockStats) Gauge(stat string, value float64, tags ...Tag)

Gauge mocks base method

func (*MockStats) Histogram 

func (m *MockStats) Histogram(stat string, value float64, tags ...Tag)

Histogram mocks base method

func (*MockStats) Scope 

func (m *MockStats) Scope(scope string, scopes ...string) Stats

Scope mocks base method

func (*MockStats) Timing 

func (m *MockStats) Timing(stat string, value time.Duration, tags ...Tag)

Timing mocks base method

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 

func DefaultBackends(backends ...string) Option

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 

func NewAsyncStats(s Stats) Stats

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 

func NewMulti(statses ...Stats) Stats

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 

func NewRecordingStats(ch chan<- Recorded) Stats

NewRecordingStats returns a Stats implementation that records calls on the given channel.

func NewRollUp 

func NewRollUp(root Stats) Stats

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

type Tag 

type Tag struct {
	K string
	V string
}

Tag is an optional piece of metadata to be added to one or more stat points

func NewKVTag 

func NewKVTag(k, v string) Tag

NewKVTag produces a new tag from a key/value pair

func NewTag 

func NewTag(tag string) Tag

NewTag produces a new tag from a string

Source Files

View all Source files

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.