speed

package module
v1.0.0-alpha Latest Latest
Warning

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

 Go to latest Published: Jul 11, 2016 License: MIT Imports: 14 Imported by: 106

README

Speed

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

A Google Summer of Code 2016 project!

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 PCP Install.md.

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

Getting the library

First download the package without installing it

go get -d github.com/performancecopilot/speed

then go to the source and run make

cd $GOPATH/src/github.com/performancecopilot/speed
make

to install dependencies and build the package

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

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
	MetricLength         = 104
	ValueLength          = 32
	InstanceLength       = 80
	InstanceDomainLength = 32
	StringLength         = 256
)

byte lengths of different components in an mmv file

View Source 
const MaxDataValueSize = 16

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

View Source 
const MaxMetricNameLength = 63

MaxMetricNameLength is the maximum length for a metric name

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 = "1.0.0-alpha"

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

This section is empty.

Types

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

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
}

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(string, interface{}) error
}

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

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

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

type MetricType 

type MetricType int32

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

const (
	NoSupportType       MetricType = -1
	Int32Type           MetricType = 0
	Uint32Type          MetricType = 1
	Int64Type           MetricType = 2
	Uint64Type          MetricType = 3
	FloatType           MetricType = 4
	DoubleType          MetricType = 5
	StringType          MetricType = 6
	AggregateType       MetricType = 7
	AggregateStaticType MetricType = 8
	EventType           MetricType = 9
	HighresEventType    MetricType = 10
	UnknownType         MetricType = 255
)

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

func (m MetricType) WriteVal(val interface{}, b bytebuffer.Buffer) error

WriteVal implements value writer for the current MetricType to a buffer

type MetricUnit 

type MetricUnit interface {
	// 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 PCPInstanceDomain 

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

PCPInstanceDomain wraps a PCP compatible instance domain

func NewPCPInstanceDomain 

func NewPCPInstanceDomain(name string, instances []string, shortDescription, longDescription 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) 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 {
	sync.RWMutex
	*PCPMetricDesc
	// 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, shortdesc, longdesc string) (*PCPInstanceMetric, error)

NewPCPInstanceMetric creates a new instance of PCPSingletonMetric

func (*PCPInstanceMetric) Indom 

func (m *PCPInstanceMetric) Indom() *PCPInstanceDomain

Indom returns the instance domain for the metric

func (*PCPInstanceMetric) SetInstance 

func (m *PCPInstanceMetric) SetInstance(instance string, val interface{}) 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() *PCPString

	LongDescription() *PCPString
}

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

type PCPMetricDesc 

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

PCPMetricDesc is a metric metadata wrapper each metric type can wrap its metadata by containing a PCPMetricDesc type and only define its own specific properties assuming PCPMetricDesc will handle the rest

when writing, this type is supposed to map directly to the pmDesc struct as defined in PCP core

func (*PCPMetricDesc) Description 

func (md *PCPMetricDesc) Description() string

Description returns the description for PCPMetric

func (*PCPMetricDesc) ID 

func (md *PCPMetricDesc) ID() uint32

ID returns the generated id for PCPMetric

func (*PCPMetricDesc) LongDescription 

func (md *PCPMetricDesc) LongDescription() *PCPString

LongDescription returns the longdesc value

func (*PCPMetricDesc) Name 

func (md *PCPMetricDesc) Name() string

Name returns the generated id for PCPMetric

func (*PCPMetricDesc) Semantics 

func (md *PCPMetricDesc) Semantics() MetricSemantics

Semantics returns the current stored value for PCPMetric

func (*PCPMetricDesc) ShortDescription 

func (md *PCPMetricDesc) ShortDescription() *PCPString

ShortDescription returns the shortdesc value

func (*PCPMetricDesc) Type 

func (md *PCPMetricDesc) Type() MetricType

Type returns the type for PCPMetric

func (*PCPMetricDesc) Unit 

func (md *PCPMetricDesc) Unit() MetricUnit

Unit returns the unit for PCPMetric

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{}, s MetricSemantics, t MetricType, 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 {
	sync.RWMutex
	*PCPMetricDesc
	// 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, shortdesc, longdesc string) (*PCPSingletonMetric, error)

NewPCPSingletonMetric creates a new instance of PCPSingletonMetric

func (*PCPSingletonMetric) Indom 

func (m *PCPSingletonMetric) Indom() *PCPInstanceDomain

Indom returns the instance domain for a PCPSingletonMetric

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 PCPString 

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

PCPString defines a string that also has a memory offset containing the location where it will be written

func NewPCPString 

func NewPCPString(s string) *PCPString

NewPCPString creates a new instance of a PCPString from a raw string

func (*PCPString) String 

func (s *PCPString) String() string

type PCPWriter 

type PCPWriter struct {
	sync.Mutex
	// contains filtered or unexported fields
}

PCPWriter implements a writer that can write PCP compatible MMV files

func NewPCPWriter 

func NewPCPWriter(name string, flag MMVFlag) (*PCPWriter, error)

NewPCPWriter initializes a new PCPWriter object

func (*PCPWriter) Length 

func (w *PCPWriter) Length() int

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

func (*PCPWriter) Register 

func (w *PCPWriter) Register(m Metric) error

Register is simply a shorthand for Registry().AddMetric

func (*PCPWriter) RegisterIndom 

func (w *PCPWriter) RegisterIndom(indom InstanceDomain) error

RegisterIndom is simply a shorthand for Registry().AddInstanceDomain

func (*PCPWriter) RegisterString 

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

RegisterString is simply a shorthand for Registry().AddMetricByString

func (*PCPWriter) Registry 

func (w *PCPWriter) Registry() Registry

Registry returns a writer's registry

func (*PCPWriter) Start 

func (w *PCPWriter) Start() error

Start dumps existing registry data

func (*PCPWriter) Stop 

func (w *PCPWriter) Stop() error

Stop removes existing mapping and cleans up

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{}, s MetricSemantics, t MetricType, 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
}

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

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

type Writer 

type Writer interface {
	// a writer must contain a registry of metrics and instance domains
	Registry() Registry

	// writes an mmv file
	Start() error

	// stops writing and cleans up
	Stop() error

	// returns the number of bytes that will be written by the current writer
	Length() int

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

	// adds an instance domain to be written
	RegisterIndom(InstanceDomain) error

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

Writer defines the interface of a MMV file writer's properties

Source Files

View all Source files

Directories

Path Synopsis
Package bytebuffer implements a java like bytebuffer for go 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 bytebuffer implements a java like bytebuffer for go 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 example from mmv.py in PCP core (https://github.com/performancecopilot/pcp/blob/master/src/python/pcp/mmv.py#L21-L70)
 A golang implementation of the acme factory example from mmv.py in PCP core (https://github.com/performancecopilot/pcp/blob/master/src/python/pcp/mmv.py#L21-L70)
instance_string
simple
singleton_counter
singleton_string
this example showcases speeds metric inference from strings property
 this example showcases speeds metric inference from strings property

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.