speed

package module
v2.0.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Apr 5, 2017 License: MIT Imports: 16 Imported by: 0

README

Speed

Golang implementation of the Performance Co-Pilot (PCP) instrumentation API

A Google Summer of Code 2016 project!

Build Status Build status Coverage Status GoDoc Go Report Card

Install

Prerequisites

PCP

Install Performance Co-Pilot on your local machine, either using prebuilt archives or by getting and building the source code. For detailed instructions, read the page from vector documentation. For building from source on ubuntu 14.04, a simplified list of steps is here

Go

Set up a go environment on your computer. For more information about these steps, please read how to write go code, or watch the video

  • download and install go 1.6 or above from https://golang.org/dl

  • set up $GOPATH to the root folder where you want to keep your go code

  • add $GOPATH/bin to your $PATH by adding export PATH=$GOPATH/bin:$PATH to your shell configuration file, such as to your .bashrc, if using a Bourne shell variant.

[Optional] Vector

Vector is an on premise visualization tool for metrics exposed using Performance Co-Pilot. For more read the official documentation and play around with the online demo

Getting the library

go get github.com/performancecopilot/speed

Getting the examples

All examples are executable go programs. Simply doing

go get github.com/performancecopilot/speed/examples/<example name>

will get the example and add an executable to $GOPATH/bin. If it is on your path, simply doing

<example name>

will run the binary, running the example

Walkthrough

There are 3 main components defined in the library, a Client, a Registry and a Metric. A client is created using an application name, and the same name is used to create a memory mapped file in PCP_TMP_DIR. Each client contains a registry of metrics that it holds, and will publish on being activated. It also has a SetFlag method allowing you to set a mmv flag while a mapping is not active, to one of three values, NoPrefixFlag, ProcessFlag and SentinelFlag. The ProcessFlag is the default and reports metrics prefixed with the application name (i.e. like mmv.app_name.metric.name). Setting it to NoPrefixFlag will report metrics without being prefixed with the application name (i.e. like mmv.metric.name) which can lead to namespace collisions, so be sure of what you're doing.

A client can register metrics to report through 2 interfaces, the first is the Register method, that takes a raw metric object. The other is using RegisterString, that can take a string with metrics and instances to register similar to the interface in parfait, along with type, semantics and unit, in that order. A client can be activated by calling the Start method, deactivated by the Stop method. While a client is active, no new metrics can be registered but it is possible to stop existing client for metric registration.

Each client contains an instance of the Registry interface, which can give different information like the number of registered metrics and instance domains. It also exports methods to register metrics and instance domains.

Finally, metrics are defined as implementations of different metric interfaces, but they all implement the Metric interface, the different metric types defined are

SingletonMetric

This type defines a metric with no instance domain and only one value. It requires type, semantics and unit for construction, and optionally takes a couple of description strings. A simple construction

metric, err := speed.NewPCPSingletonMetric(
	42,                                                             // initial value
	"simple.counter",                                               // name
	speed.Int32Type,                                                // type
	speed.CounterSemantics,                                         // semantics
	speed.OneUnit,                                                  // unit
	"A Simple Metric",                                              // short description
	"This is a simple counter metric to demonstrate the speed API", // long description
)

A SingletonMetric supports a Val method that returns the metric value and a Set(interface{}) method that sets the metric value.

InstanceMetric

An InstanceMetric is a single metric object containing multiple values of the same type for multiple instances. It also requires an instance domain along with type, semantics and unit for construction, and optionally takes a couple of description strings. A simple construction

indom, err := speed.NewPCPInstanceDomain(
	"Acme Products",                                          // name
	[]string{"Anvils", "Rockets", "Giant_Rubber_Bands"},      // instances
	"Acme products",                                          // short description
	"Most popular products produced by the Acme Corporation", // long description
)

...

countmetric, err := speed.NewPCPInstanceMetric(
	speed.Instances{
		"Anvils":             0,
		"Rockets":            0,
		"Giant_Rubber_Bands": 0,
	},
	"products.count",
	indom,
	speed.Uint64Type,
	speed.CounterSemantics,
	speed.OneUnit,
	"Acme factory product throughput",
	`Monotonic increasing counter of products produced in the Acme Corporation
	factory since starting the Acme production application.  Quality guaranteed.`,
)

An instance metric supports a ValInstance(string) method that returns the value as well as a SetInstance(interface{}, string) that sets the value of a particular instance.

Counter

A counter is simply a PCPSingletonMetric with Int64Type, CounterSemantics and OneUnit. It can optionally take a short and a long description.

A simple example

c, err := speed.NewPCPCounter(0, "a.simple.counter")

a counter supports Set(int64) to set a value, Inc(int64) to increment by a custom delta and Up() to increment by 1.

CounterVector

A CounterVector is a PCPInstanceMetric , with Int64Type, CounterSemantics and OneUnit and an instance domain created and registered on initialization, with the name metric_name.indom.

A simple example

c, err := speed.NewPCPCounterVector(
	map[string]uint64{
		"instance1": 0,
		"instance2": 1,
	}, "another.simple.counter"
)

It supports Val(string), Set(uint64, string), Inc(uint64, string) and Up(string) amongst other things.

Gauge

A Gauge is a simple SingletonMetric storing float64 values, i.e. a PCP Singleton Metric with DoubleType, InstantSemantics and OneUnit.

A simple example

g, err := speed.NewPCPGauge(0, "a.sample.gauge")

supports Val(), Set(float64), Inc(float64) and Dec(float64)

GaugeVector

A Gauge Vector is a PCP instance metric with DoubleType, InstantSemantics and OneUnit and an autogenerated instance domain. A simple example

g, err := NewPCPGaugeVector(map[string]float64{
	"instance1": 1.2,
	"instance2": 2.4,
}, "met")

supports Val(string), Set(float64, string), Inc(float64, string) and Dec(float64, string)

Timer

A timer stores the time elapsed for different operations. It is not compatible with PCP's elapsed type metrics. It takes a name and a TimeUnit for construction.

timer, err := speed.NewPCPTimer("test", speed.NanosecondUnit)

calling timer.Start() signals the start of an operation

calling timer.Stop() signals end of an operation and will return the total elapsed time calculated by the metric so far.

Histogram

A histogram implements a PCP Instance Metric that reports the mean, variance and standard_deviation while using a histogram backed by codahale's hdrhistogram implementation in golang. Other than these, it also returns a custom percentile and buckets for plotting graphs. It requires a low and a high value and the number of significant figures used at the time of construction.

m, err := speed.NewPCPHistogram("hist", 0, 1000, 5)

Visualization through Vector

Vector supports adding custom widgets for custom metrics. However, that requires you to rebuild vector from scratch after adding the widget configuration. But if it is a one time thing, its worth it. For example here is the configuration I added to display the metric from the basic_histogram example

{
	name: 'mmv.histogram_test.hist',
	title: 'speed basic histogram example',
	directive: 'line-time-series',
	dataAttrName: 'data',
	dataModelType: CumulativeMetricDataModel,
	dataModelOptions: {
		name: 'mmv.histogram_test.hist'
	},
	size: {
		width: '50%',
		height: '250px'
	},
	enableVerticalResize: false,
	group: 'speed',
	attrs: {
		forcey: 100,
		percentage: false
	}
}

and the visualization I got

screenshot from 2016-08-27 01 05 56

Go Kit

Go kit provides a wrapper package over speed that can be used for building microservices that expose metrics using PCP.

For modified versions of the examples in go-kit that use pcp to report metrics, see suyash/kit-pcp-examples

Projects using Speed

Documentation

Overview

Package speed implements a golang client for the Performance Co-Pilot instrumentation API.

It is based on the C/Perl/Python API implemented in PCP core as well as the Java API implemented by `parfait`, a separate project.

Some examples on using the API are implemented as executable go programs in the `examples` subdirectory.

Index

Constants

View Source 
const (
	HeaderLength         = 40
	TocLength            = 16
	Metric1Length        = 104
	Metric2Length        = 48
	ValueLength          = 32
	Instance1Length      = 80
	Instance2Length      = 24
	InstanceDomainLength = 32
	StringLength         = 256
)

byte lengths of different components in an mmv file

View Source 
const (
	HistogramMin = 0
	HistogramMax = 3600000000
)

the maximum and minimum values that can be recorded by a histogram

View Source 
const MaxDataValueSize = 16

MaxDataValueSize is the maximum byte length for a stored metric value, unless it is a string

View Source 
const MaxV1NameLength = 63

MaxV1NameLength is the maximum length for a metric/instance name under MMV format 1

View Source 
const PCPClusterIDBitLength = 12

PCPClusterIDBitLength is the bit length of the cluster id for a set of PCP metrics

View Source 
const PCPInstanceDomainBitLength = 22

PCPInstanceDomainBitLength is the maximum bit length of a PCP Instance Domain

see: https://github.com/performancecopilot/pcp/blob/master/src/include/pcp/impl.h#L102-L121

View Source 
const PCPMetricItemBitLength = 10

PCPMetricItemBitLength is the maximum bit size of a PCP Metric id.

see: https://github.com/performancecopilot/pcp/blob/master/src/include/pcp/impl.h#L102-L121

View Source 
const Version = "2.0.0"

Version is the last tagged version of the package

Variables

View Source 
var EraseFileOnStop = false

EraseFileOnStop if set to true, will also delete the memory mapped file

Functions

func AddLogWriter 

func AddLogWriter(writer io.Writer)

AddLogWriter adds a new io.Writer as a target for writing logs.

func EnableLogging 

func EnableLogging(enable bool)

EnableLogging logging enables logging for logrus if true is passed and disables it if false is passed.

func SetLogWriters 

func SetLogWriters(writers ...io.Writer)

SetLogWriters will set the passed io.Writer instances as targets for writing logs.

Types

type Client 

type Client interface {
	// a client must contain a registry of metrics
	Registry() Registry

	// starts monitoring
	Start() error

	// Start that will panic on failure
	MustStart()

	// stop monitoring
	Stop() error

	// Stop that will panic on failure
	MustStop()

	// adds a metric to be monitored
	Register(Metric) error

	// tries to add a metric to be written and panics on error
	MustRegister(Metric)

	// adds metric from a string
	RegisterString(string, interface{}, MetricType, MetricSemantics, MetricUnit) (Metric, error)

	// tries to add a metric from a string and panics on an error
	MustRegisterString(string, interface{}, MetricType, MetricSemantics, MetricUnit) Metric
}

Client defines the interface for a type that can talk to an instrumentation agent

type CountUnit 

type CountUnit uint32

CountUnit is a type representing a counted quantity. 

const OneUnit CountUnit = 1<<20 | iota<<8

OneUnit represents the only CountUnit. For count units bits 8-11 are 1 and bits 21-24 are scale.

func (CountUnit) PMAPI 

func (c CountUnit) PMAPI() uint32

PMAPI returns the PMAPI representation for a CountUnit.

func (CountUnit) String 

func (i CountUnit) String() string

type Counter 

type Counter interface {
	Metric

	Val() int64
	Set(int64) error

	Inc(int64) error
	MustInc(int64)

	Up() // same as MustInc(1)
}

Counter defines a metric that holds a single value that can only be incremented.

type CounterVector 

type CounterVector interface {
	Metric

	Val(string) (int64, error)

	Set(int64, string) error
	MustSet(int64, string)
	SetAll(int64)

	Inc(int64, string) error
	MustInc(int64, string)
	IncAll(int64)

	Up(string)
	UpAll()
}

CounterVector defines a Counter on multiple instances.

type Gauge 

type Gauge interface {
	Metric

	Val() float64

	Set(float64) error
	MustSet(float64)

	Inc(float64) error
	Dec(float64) error

	MustInc(float64)
	MustDec(float64)
}

Gauge defines a metric that holds a single double value that can be incremented or decremented.

type GaugeVector 

type GaugeVector interface {
	Metric

	Val(string) (float64, error)

	Set(float64, string) error
	MustSet(float64, string)
	SetAll(float64)

	Inc(float64, string) error
	MustInc(float64, string)
	IncAll(float64)

	Dec(float64, string) error
	MustDec(float64, string)
	DecAll(float64)
}

GaugeVector defines a Gauge on multiple instances

type Histogram 

type Histogram interface {
	Max() int64 // Maximum value recorded so far
	Min() int64 // Minimum value recorded so far

	High() int64 // Highest allowed value
	Low() int64  // Lowest allowed value

	Record(int64) error         // Records a new value
	RecordN(int64, int64) error // Records multiple instances of the same value

	MustRecord(int64)
	MustRecordN(int64, int64)

	Mean() float64              // Mean of all recorded data
	Variance() float64          // Variance of all recorded data
	StandardDeviation() float64 // StandardDeviation of all recorded data
	Percentile(float64) int64   // Percentile returns the value at the passed percentile
}

Histogram defines a metric that records a distribution of data

type HistogramBucket 

type HistogramBucket struct {
	From, To, Count int64
}

HistogramBucket is a single histogram bucket within a fixed range.

type InstanceDomain 

type InstanceDomain interface {
	ID() uint32                   // unique identifier for the instance domain
	Name() string                 // name of the instance domain
	Description() string          // description for the instance domain
	HasInstance(name string) bool // checks if an instance is in the indom
	InstanceCount() int           // returns the number of instances in the indom
	Instances() []string          // returns a slice of instances in the instance domain
}

InstanceDomain defines the interface for an instance domain

type InstanceMetric 

type InstanceMetric interface {
	Metric

	// gets the value of a particular instance
	ValInstance(string) (interface{}, error)

	// sets the value of a particular instance
	SetInstance(interface{}, string) error

	// tries to set the value of a particular instance and panics on error
	MustSetInstance(interface{}, string)

	// returns a slice containing all instances in the metric
	Instances() []string
}

InstanceMetric defines the interface for a metric that stores multiple values in instances and instance domains.

type Instances 

type Instances map[string]interface{}

Instances defines a valid collection of instance name and values

func (Instances) Keys 

func (i Instances) Keys() []string

Keys collects and returns all the keys in all instance values

type MMVFlag 

type MMVFlag int

MMVFlag represents an enumerated type to represent mmv flag values 

const (
	NoPrefixFlag MMVFlag = 1 << iota
	ProcessFlag
	SentinelFlag
)

values for MMVFlag

func (MMVFlag) String 

func (i MMVFlag) String() string

type Metric 

type Metric interface {
	// gets the unique id generated for this metric
	ID() uint32

	// gets the name for the metric
	Name() string

	// gets the type of a metric
	Type() MetricType

	// gets the unit of a metric
	Unit() MetricUnit

	// gets the semantics for a metric
	Semantics() MetricSemantics

	// gets the description of a metric
	Description() string
}

Metric defines the general interface a type needs to implement to qualify as a valid PCP metric.

type MetricSemantics 

type MetricSemantics int32

MetricSemantics represents an enumerated type representing the possible values for the semantics of a metric. 

const (
	NoSemantics MetricSemantics = iota
	CounterSemantics

	InstantSemantics
	DiscreteSemantics
)

Possible values for MetricSemantics.

func (MetricSemantics) String 

func (i MetricSemantics) String() string

type MetricType 

type MetricType int32

MetricType is an enumerated type representing all valid types for a metric. 

const (
	Int32Type MetricType = iota
	Uint32Type
	Int64Type
	Uint64Type
	FloatType
	DoubleType
	StringType
)

Possible values for a MetricType.

func (MetricType) IsCompatible 

func (m MetricType) IsCompatible(val interface{}) bool

IsCompatible checks if the passed value is compatible with the current MetricType.

func (MetricType) String 

func (i MetricType) String() string

type MetricUnit 

type MetricUnit interface {
	fmt.Stringer

	// return 32 bit PMAPI representation for the unit
	// see: https://github.com/performancecopilot/pcp/blob/master/src/include/pcp/pmapi.h#L61-L101
	PMAPI() uint32
}

MetricUnit defines the interface for a unit type for speed.

type PCPClient 

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

PCPClient implements a client that can generate instrumentation for PCP

func NewPCPClient 

func NewPCPClient(name string) (*PCPClient, error)

NewPCPClient initializes a new PCPClient object

func NewPCPClientWithRegistry 

func NewPCPClientWithRegistry(name string, registry *PCPRegistry) (*PCPClient, error)

NewPCPClientWithRegistry initializes a new PCPClient object with the given registry

func (*PCPClient) Length 

func (c *PCPClient) Length() int

Length returns the byte length of data in the mmv file written by the current writer

func (*PCPClient) MustRegister 

func (c *PCPClient) MustRegister(m Metric)

MustRegister is simply a Register that can panic

func (*PCPClient) MustRegisterIndom 

func (c *PCPClient) MustRegisterIndom(indom InstanceDomain)

MustRegisterIndom is simply a RegisterIndom that can panic

func (*PCPClient) MustRegisterString 

func (c *PCPClient) MustRegisterString(str string, val interface{}, t MetricType, s MetricSemantics, u MetricUnit) Metric

MustRegisterString is simply a RegisterString that panics

func (*PCPClient) MustStart 

func (c *PCPClient) MustStart()

MustStart is a start that panics

func (*PCPClient) MustStop 

func (c *PCPClient) MustStop()

MustStop is a stop that panics

func (*PCPClient) Register 

func (c *PCPClient) Register(m Metric) error

Register is simply a shorthand for Registry().AddMetric

func (*PCPClient) RegisterIndom 

func (c *PCPClient) RegisterIndom(indom InstanceDomain) error

RegisterIndom is simply a shorthand for Registry().AddInstanceDomain

func (*PCPClient) RegisterString 

func (c *PCPClient) RegisterString(str string, val interface{}, t MetricType, s MetricSemantics, u MetricUnit) (Metric, error)

RegisterString is simply a shorthand for Registry().AddMetricByString

func (*PCPClient) Registry 

func (c *PCPClient) Registry() Registry

Registry returns a writer's registry

func (*PCPClient) SetFlag 

func (c *PCPClient) SetFlag(flag MMVFlag) error

SetFlag sets the MMVflag for the client

func (*PCPClient) Start 

func (c *PCPClient) Start() error

Start dumps existing registry data

func (*PCPClient) Stop 

func (c *PCPClient) Stop() error

Stop removes existing mapping and cleans up

type PCPCounter 

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

PCPCounter implements a PCP compatible Counter Metric.

func NewPCPCounter 

func NewPCPCounter(val int64, name string, desc ...string) (*PCPCounter, error)

NewPCPCounter creates a new PCPCounter instance. It requires an initial int64 value and a metric name for construction. optionally it can also take a couple of description strings that are used as short and long descriptions respectively. Internally it creates a PCP SingletonMetric with Int64Type, CounterSemantics and CountUnit.

func (*PCPCounter) Inc 

func (c *PCPCounter) Inc(val int64) error

Inc increases the stored counter's value by the passed increment.

func (PCPCounter) Indom 

func (m PCPCounter) Indom() *PCPInstanceDomain

func (*PCPCounter) MustInc 

func (c *PCPCounter) MustInc(val int64)

MustInc is Inc that panics on failure.

func (*PCPCounter) Set 

func (c *PCPCounter) Set(val int64) error

Set sets the value of the counter.

func (*PCPCounter) Up 

func (c *PCPCounter) Up()

Up increases the counter by 1.

func (*PCPCounter) Val 

func (c *PCPCounter) Val() int64

Val returns the current value of the counter.

type PCPCounterVector 

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

PCPCounterVector implements a CounterVector

func NewPCPCounterVector 

func NewPCPCounterVector(values map[string]int64, name string, desc ...string) (*PCPCounterVector, error)

NewPCPCounterVector creates a new instance of a PCPCounterVector. it requires a metric name and a set of instance names and values as a map. it can optionally accept a couple of strings as short and long descriptions of the metric. Internally it uses a PCP InstanceMetric with Int64Type, CounterSemantics and CountUnit.

func (*PCPCounterVector) Inc 

func (c *PCPCounterVector) Inc(inc int64, instance string) error

Inc increments the value of a particular instance of PCPCounterVector.

func (*PCPCounterVector) IncAll 

func (c *PCPCounterVector) IncAll(val int64)

IncAll increments all instances by the same value and panics on an error.

func (PCPCounterVector) Indom 

func (m PCPCounterVector) Indom() *PCPInstanceDomain

Indom returns the instance domain for the metric.

func (PCPCounterVector) Instances 

func (m PCPCounterVector) Instances() []string

Instances returns a slice containing all instances in the InstanceMetric. Basically a shorthand for metric.Indom().Instances().

func (*PCPCounterVector) MustInc 

func (c *PCPCounterVector) MustInc(inc int64, instance string)

MustInc panics if Inc fails.

func (*PCPCounterVector) MustSet 

func (c *PCPCounterVector) MustSet(val int64, instance string)

MustSet panics if Set fails.

func (*PCPCounterVector) Set 

func (c *PCPCounterVector) Set(val int64, instance string) error

Set sets the value of a particular instance of PCPCounterVector.

func (*PCPCounterVector) SetAll 

func (c *PCPCounterVector) SetAll(val int64)

SetAll sets all instances to the same value and panics on an error.

func (*PCPCounterVector) Up 

func (c *PCPCounterVector) Up(instance string)

Up increments the value of a particular instance ny 1.

func (*PCPCounterVector) UpAll 

func (c *PCPCounterVector) UpAll()

UpAll ups all instances and panics on an error.

func (*PCPCounterVector) Val 

func (c *PCPCounterVector) Val(instance string) (int64, error)

Val returns the value of a particular instance of PCPCounterVector.

type PCPGauge 

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

PCPGauge defines a PCP compatible Gauge metric

func NewPCPGauge 

func NewPCPGauge(val float64, name string, desc ...string) (*PCPGauge, error)

NewPCPGauge creates a new PCPGauge instance. Tt requires an initial float64 value and a metric name for construction. Optionally it can also take a couple of description strings that are used as short and long descriptions respectively. Internally it creates a PCP SingletonMetric with DoubleType, InstantSemantics and CountUnit.

func (*PCPGauge) Dec 

func (g *PCPGauge) Dec(val float64) error

Dec adds a value to the existing Gauge value.

func (*PCPGauge) Inc 

func (g *PCPGauge) Inc(val float64) error

Inc adds a value to the existing Gauge value.

func (PCPGauge) Indom 

func (m PCPGauge) Indom() *PCPInstanceDomain

func (*PCPGauge) MustDec 

func (g *PCPGauge) MustDec(val float64)

MustDec will panic if Dec fails.

func (*PCPGauge) MustInc 

func (g *PCPGauge) MustInc(val float64)

MustInc will panic if Inc fails.

func (*PCPGauge) MustSet 

func (g *PCPGauge) MustSet(val float64)

MustSet will panic if Set fails.

func (*PCPGauge) Set 

func (g *PCPGauge) Set(val float64) error

Set sets the current value of the Gauge.

func (*PCPGauge) Val 

func (g *PCPGauge) Val() float64

Val returns the current value of the Gauge.

type PCPGaugeVector 

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

PCPGaugeVector implements a GaugeVector

func NewPCPGaugeVector 

func NewPCPGaugeVector(values map[string]float64, name string, desc ...string) (*PCPGaugeVector, error)

NewPCPGaugeVector creates a new instance of a PCPGaugeVector. It requires a name and map of instance names to their values. Optionally, it can also accept a couple of strings providing more details about the metric.

func (*PCPGaugeVector) Dec 

func (g *PCPGaugeVector) Dec(inc float64, instance string) error

Dec decrements the value of a particular instance of PCPGaugeVector

func (*PCPGaugeVector) DecAll 

func (g *PCPGaugeVector) DecAll(val float64)

DecAll decrements all instances by the same value and panics on an error

func (*PCPGaugeVector) Inc 

func (g *PCPGaugeVector) Inc(inc float64, instance string) error

Inc increments the value of a particular instance of PCPGaugeVector

func (*PCPGaugeVector) IncAll 

func (g *PCPGaugeVector) IncAll(val float64)

IncAll increments all instances by the same value and panics on an error

func (PCPGaugeVector) Indom 

func (m PCPGaugeVector) Indom() *PCPInstanceDomain

Indom returns the instance domain for the metric.

func (PCPGaugeVector) Instances 

func (m PCPGaugeVector) Instances() []string

Instances returns a slice containing all instances in the InstanceMetric. Basically a shorthand for metric.Indom().Instances().

func (*PCPGaugeVector) MustDec 

func (g *PCPGaugeVector) MustDec(inc float64, instance string)

MustDec panics if Dec fails

func (*PCPGaugeVector) MustInc 

func (g *PCPGaugeVector) MustInc(inc float64, instance string)

MustInc panics if Inc fails

func (*PCPGaugeVector) MustSet 

func (g *PCPGaugeVector) MustSet(val float64, instance string)

MustSet panics if Set fails

func (*PCPGaugeVector) Set 

func (g *PCPGaugeVector) Set(val float64, instance string) error

Set sets the value of a particular instance of PCPGaugeVector

func (*PCPGaugeVector) SetAll 

func (g *PCPGaugeVector) SetAll(val float64)

SetAll sets all instances to the same value and panics on an error

func (*PCPGaugeVector) Val 

func (g *PCPGaugeVector) Val(instance string) (float64, error)

Val returns the value of a particular instance of PCPGaugeVector

type PCPHistogram 

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

PCPHistogram implements a histogram for PCP backed by the coda hale hdrhistogram https://github.com/codahale/hdrhistogram

func NewPCPHistogram 

func NewPCPHistogram(name string, low, high int64, sigfigures int, unit MetricUnit, desc ...string) (*PCPHistogram, error)

NewPCPHistogram returns a new instance of PCPHistogram. The lowest value for `low` is 0. The highest value for `high` is 3,600,000,000. `low` **must** be less than `high`. The value of `sigfigures` can be between 1 and 5. It also requires a unit to be explicitly passed for construction. Optionally, a couple of description strings may be passed as the short and long descriptions of the metric.

func (*PCPHistogram) Buckets 

func (h *PCPHistogram) Buckets() []*HistogramBucket

Buckets returns a list of histogram buckets.

func (*PCPHistogram) High 

func (h *PCPHistogram) High() int64

High returns the maximum recordable value.

func (PCPHistogram) Indom 

func (m PCPHistogram) Indom() *PCPInstanceDomain

Indom returns the instance domain for the metric.

func (PCPHistogram) Instances 

func (m PCPHistogram) Instances() []string

Instances returns a slice containing all instances in the InstanceMetric. Basically a shorthand for metric.Indom().Instances().

func (*PCPHistogram) Low 

func (h *PCPHistogram) Low() int64

Low returns the minimum recordable value.

func (*PCPHistogram) Max 

func (h *PCPHistogram) Max() int64

Max returns the maximum recorded value so far.

func (*PCPHistogram) Mean 

func (h *PCPHistogram) Mean() float64

Mean returns the mean of all values recorded so far.

func (*PCPHistogram) Min 

func (h *PCPHistogram) Min() int64

Min returns the minimum recorded value so far.

func (*PCPHistogram) MustRecord 

func (h *PCPHistogram) MustRecord(val int64)

MustRecord panics if Record fails.

func (*PCPHistogram) MustRecordN 

func (h *PCPHistogram) MustRecordN(val, n int64)

MustRecordN panics if RecordN fails.

func (*PCPHistogram) Percentile 

func (h *PCPHistogram) Percentile(p float64) int64

Percentile returns the value at the passed percentile.

func (*PCPHistogram) Record 

func (h *PCPHistogram) Record(val int64) error

Record records a new value.

func (*PCPHistogram) RecordN 

func (h *PCPHistogram) RecordN(val, n int64) error

RecordN records multiple instances of the same value.

func (*PCPHistogram) StandardDeviation 

func (h *PCPHistogram) StandardDeviation() float64

StandardDeviation returns the standard deviation of all values recorded so far.

func (*PCPHistogram) Variance 

func (h *PCPHistogram) Variance() float64

Variance returns the variance of all values recorded so far.

type PCPInstanceDomain 

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

PCPInstanceDomain wraps a PCP compatible instance domain

func NewPCPInstanceDomain 

func NewPCPInstanceDomain(name string, instances []string, desc ...string) (*PCPInstanceDomain, error)

NewPCPInstanceDomain creates a new instance domain or returns an already created one for the passed name NOTE: this is different from parfait's idea of generating ids for InstanceDomains We simply generate a unique 32 bit hash for an instance domain name, and if it has not already been created, we create it, otherwise we return the already created version

func (*PCPInstanceDomain) Description 

func (indom *PCPInstanceDomain) Description() string

Description returns the description for PCPInstanceDomain

func (*PCPInstanceDomain) HasInstance 

func (indom *PCPInstanceDomain) HasInstance(name string) bool

HasInstance returns true if an instance of the specified name is in the Indom

func (*PCPInstanceDomain) ID 

func (indom *PCPInstanceDomain) ID() uint32

ID returns the id for PCPInstanceDomain

func (*PCPInstanceDomain) InstanceCount 

func (indom *PCPInstanceDomain) InstanceCount() int

InstanceCount returns the number of instances in the current instance domain

func (*PCPInstanceDomain) Instances 

func (indom *PCPInstanceDomain) Instances() []string

Instances returns a slice of defined instances for the instance domain

func (*PCPInstanceDomain) MatchInstances 

func (indom *PCPInstanceDomain) MatchInstances(ins []string) bool

MatchInstances returns true if the passed InstanceDomain has exactly the same instances as the passed array

func (*PCPInstanceDomain) Name 

func (indom *PCPInstanceDomain) Name() string

Name returns the name for PCPInstanceDomain

func (*PCPInstanceDomain) String 

func (indom *PCPInstanceDomain) String() string

type PCPInstanceMetric 

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

PCPInstanceMetric represents a PCPMetric that can have multiple values over multiple instances in an instance domain.

func NewPCPInstanceMetric 

func NewPCPInstanceMetric(vals Instances, name string, indom *PCPInstanceDomain, t MetricType, s MetricSemantics, u MetricUnit, desc ...string) (*PCPInstanceMetric, error)

NewPCPInstanceMetric creates a new instance of PCPSingletonMetric. it takes 2 extra optional strings as short and long description parameters, which on not being present are set to empty strings.

func (PCPInstanceMetric) Indom 

func (m PCPInstanceMetric) Indom() *PCPInstanceDomain

Indom returns the instance domain for the metric.

func (PCPInstanceMetric) Instances 

func (m PCPInstanceMetric) Instances() []string

Instances returns a slice containing all instances in the InstanceMetric. Basically a shorthand for metric.Indom().Instances().

func (*PCPInstanceMetric) MustSetInstance 

func (m *PCPInstanceMetric) MustSetInstance(val interface{}, instance string)

MustSetInstance is a SetInstance that panics.

func (*PCPInstanceMetric) SetInstance 

func (m *PCPInstanceMetric) SetInstance(val interface{}, instance string) error

SetInstance sets the value for a particular instance of the metric.

func (*PCPInstanceMetric) ValInstance 

func (m *PCPInstanceMetric) ValInstance(instance string) (interface{}, error)

ValInstance returns the value for a particular instance of the metric.

type PCPMetric 

type PCPMetric interface {
	Metric

	// a PCPMetric will always have an instance domain, even if it is nil
	Indom() *PCPInstanceDomain

	ShortDescription() string

	LongDescription() string
}

PCPMetric defines the interface for a metric that is compatible with PCP.

type PCPRegistry 

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

PCPRegistry implements a registry for PCP as the client

func NewPCPRegistry 

func NewPCPRegistry() *PCPRegistry

NewPCPRegistry creates a new PCPRegistry object

func (*PCPRegistry) AddInstanceDomain 

func (r *PCPRegistry) AddInstanceDomain(indom InstanceDomain) error

AddInstanceDomain will add a new instance domain to the current registry

func (*PCPRegistry) AddInstanceDomainByName 

func (r *PCPRegistry) AddInstanceDomainByName(name string, instances []string) (InstanceDomain, error)

AddInstanceDomainByName adds an instance domain using passed parameters

func (*PCPRegistry) AddMetric 

func (r *PCPRegistry) AddMetric(m Metric) error

AddMetric will add a new metric to the current registry

func (*PCPRegistry) AddMetricByString 

func (r *PCPRegistry) AddMetricByString(str string, val interface{}, t MetricType, s MetricSemantics, u MetricUnit) (Metric, error)

AddMetricByString dynamically creates a PCPMetric

func (*PCPRegistry) HasInstanceDomain 

func (r *PCPRegistry) HasInstanceDomain(name string) bool

HasInstanceDomain returns true if the registry already has an indom of the specified name

func (*PCPRegistry) HasMetric 

func (r *PCPRegistry) HasMetric(name string) bool

HasMetric returns true if the registry already has a metric of the specified name

func (*PCPRegistry) InstanceCount 

func (r *PCPRegistry) InstanceCount() int

InstanceCount returns the number of instances across all indoms in the registry

func (*PCPRegistry) InstanceDomainCount 

func (r *PCPRegistry) InstanceDomainCount() int

InstanceDomainCount returns the number of instance domains in the registry

func (*PCPRegistry) MetricCount 

func (r *PCPRegistry) MetricCount() int

MetricCount returns the number of metrics in the registry

func (*PCPRegistry) StringCount 

func (r *PCPRegistry) StringCount() int

StringCount returns the number of strings in the registry

func (*PCPRegistry) ValuesCount 

func (r *PCPRegistry) ValuesCount() int

ValuesCount returns the number of values in the registry

type PCPSingletonMetric 

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

PCPSingletonMetric defines a singleton metric with no instance domain only a value and a valueoffset.

func NewPCPSingletonMetric 

func NewPCPSingletonMetric(val interface{}, name string, t MetricType, s MetricSemantics, u MetricUnit, desc ...string) (*PCPSingletonMetric, error)

NewPCPSingletonMetric creates a new instance of PCPSingletonMetric it takes 2 extra optional strings as short and long description parameters, which on not being present are set to blank strings.

func (PCPSingletonMetric) Indom 

func (m PCPSingletonMetric) Indom() *PCPInstanceDomain

func (*PCPSingletonMetric) MustSet 

func (m *PCPSingletonMetric) MustSet(val interface{})

MustSet is a Set that panics on failure.

func (*PCPSingletonMetric) Set 

func (m *PCPSingletonMetric) Set(val interface{}) error

Set Sets the current value of PCPSingletonMetric.

func (*PCPSingletonMetric) String 

func (m *PCPSingletonMetric) String() string

func (*PCPSingletonMetric) Val 

func (m *PCPSingletonMetric) Val() interface{}

Val returns the current Set value of PCPSingletonMetric.

type PCPTimer 

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

PCPTimer implements a PCP compatible Timer It also functionally implements a metric with elapsed type from PCP

func NewPCPTimer 

func NewPCPTimer(name string, unit TimeUnit, desc ...string) (*PCPTimer, error)

NewPCPTimer creates a new PCPTimer instance of the specified unit. It requires a metric name and a TimeUnit for construction. It can optionally take a couple of description strings. Internally it uses a PCP SingletonMetric.

func (PCPTimer) Indom 

func (m PCPTimer) Indom() *PCPInstanceDomain

func (*PCPTimer) Start 

func (t *PCPTimer) Start() error

Start signals the timer to start monitoring.

func (*PCPTimer) Stop 

func (t *PCPTimer) Stop() (float64, error)

Stop signals the timer to end monitoring and return elapsed time so far.

type Registry 

type Registry interface {
	// checks if an instance domain of the passed name is already present or not
	HasInstanceDomain(name string) bool

	// checks if an metric of the passed name is already present or not
	HasMetric(name string) bool

	// returns the number of Metrics in the current registry
	MetricCount() int

	// returns the number of Values in the current registry
	ValuesCount() int

	// returns the number of Instance Domains in the current registry
	InstanceDomainCount() int

	// returns the number of instances across all instance domains in the current registry
	InstanceCount() int

	// returns the number of non null strings initialized in the current registry
	StringCount() int

	// adds a InstanceDomain object to the writer
	AddInstanceDomain(InstanceDomain) error

	// adds a InstanceDomain object after constructing it using passed name and instances
	AddInstanceDomainByName(name string, instances []string) (InstanceDomain, error)

	// adds a Metric object to the writer
	AddMetric(Metric) error

	// adds a Metric object after parsing the passed string for Instances and InstanceDomains
	AddMetricByString(name string, val interface{}, t MetricType, s MetricSemantics, u MetricUnit) (Metric, error)
}

Registry defines a valid set of instance domains and metrics

type SingletonMetric 

type SingletonMetric interface {
	Metric

	// gets the value of the metric
	Val() interface{}

	// sets the value of the metric to a value, optionally returns an error on failure
	Set(interface{}) error

	// tries to set and panics on error
	MustSet(interface{})
}

SingletonMetric defines the interface for a metric that stores only one value.

type SpaceUnit 

type SpaceUnit uint32

SpaceUnit is an enumerated type representing all units for space. 

const (
	ByteUnit SpaceUnit = 1<<28 | iota<<16
	KilobyteUnit
	MegabyteUnit
	GigabyteUnit
	TerabyteUnit
	PetabyteUnit
	ExabyteUnit
)

Possible values for SpaceUnit.

func (SpaceUnit) PMAPI 

func (s SpaceUnit) PMAPI() uint32

PMAPI returns the PMAPI representation for a SpaceUnit for space units bits 0-3 are 1 and bits 13-16 are scale

func (SpaceUnit) String 

func (i SpaceUnit) String() string

type TimeUnit 

type TimeUnit uint32

TimeUnit is an enumerated type representing all possible units for representing time. 

const (
	NanosecondUnit TimeUnit = 1<<24 | iota<<12
	MicrosecondUnit
	MillisecondUnit
	SecondUnit
	MinuteUnit
	HourUnit
)

Possible Values for TimeUnit. for time units bits 4-7 are 1 and bits 17-20 are scale.

func (TimeUnit) PMAPI 

func (t TimeUnit) PMAPI() uint32

PMAPI returns the PMAPI representation for a TimeUnit.

func (TimeUnit) String 

func (i TimeUnit) String() string

type Timer 

type Timer interface {
	Metric

	Start() error
	Stop() (float64, error)
}

Timer defines a metric that accumulates time periods Start signals the beginning of monitoring. End signals the end of monitoring and adding the elapsed time to the accumulated time, and returning it.

Source Files

View all Source files

Directories

Path Synopsis
Package bytewriter implements writers that support concurrent writing within a fixed length block initially tried to use bytes.Buffer but the main restriction with that is that it does not allow the freedom to move around in the buffer.
 Package bytewriter implements writers that support concurrent writing within a fixed length block initially tried to use bytes.Buffer but the main restriction with that is that it does not allow the freedom to move around in the buffer.
examples
acme
A golang implementation of the acme factory examples from python and Java APIs The python implementation is in mmv.py in PCP core (https://github.com/performancecopilot/pcp/blob/master/src/python/pcp/mmv.py#L21-L70) The Java implementation is in examples in parfait core (https://github.com/performancecopilot/parfait/tree/master/examples/acme) To run the python version of the example that exits do go run examples/acme/main.go To run the java version of the example that runs forever, simply add a --forever flag go run examples/acme/main.go --forever
 A golang implementation of the acme factory examples from python and Java APIs The python implementation is in mmv.py in PCP core (https://github.com/performancecopilot/pcp/blob/master/src/python/pcp/mmv.py#L21-L70) The Java implementation is in examples in parfait core (https://github.com/performancecopilot/parfait/tree/master/examples/acme) To run the python version of the example that exits do go run examples/acme/main.go To run the java version of the example that runs forever, simply add a --forever flag go run examples/acme/main.go --forever
basic_histogram
http_counter
instance_string
runtime
simple
simple_string_metric
singleton_counter
singleton_string
this example showcases speeds metric inference from strings property
 this example showcases speeds metric inference from strings property
Package mmvdump implements a go port of the C mmvdump utility included in PCP Core https://github.com/performancecopilot/pcp/blob/master/src/pmdas/mmv/mmvdump.c It has been written for maximum portability with the C equivalent, without having to use cgo or any other ninja stuff the main difference is that the reader is separate from the cli with the reading primarily implemented in mmvdump.go while the cli is implemented in cmd/mmvdump the cli application is completely go gettable and outputs the same things, in mostly the same way as the C cli app, to try it out, “` go get github.com/performancecopilot/speed/mmvdump/cmd/mmvdump “`
 Package mmvdump implements a go port of the C mmvdump utility included in PCP Core https://github.com/performancecopilot/pcp/blob/master/src/pmdas/mmv/mmvdump.c It has been written for maximum portability with the C equivalent, without having to use cgo or any other ninja stuff the main difference is that the reader is separate from the cli with the reading primarily implemented in mmvdump.go while the cli is implemented in cmd/mmvdump the cli application is completely go gettable and outputs the same things, in mostly the same way as the C cli app, to try it out, “` go get github.com/performancecopilot/speed/mmvdump/cmd/mmvdump “`
cmd/mmvdump

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.