skunk

README

skunk
=====
Noel Cower


skunk is a simple wrapper around an HTTP client and some friendly-ish methods
for collecting and sending metrics to NewRelic's plugin API. It is not ready
for use.


	go get go.spiff.io/skunk


License
-------
skunk is licensed under the ISC license. The license can be found in the
'COPYING' file that should have accompanied this release.

[quote]
--
Copyright (c) 2015, Noel Cower.

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
--

Documentation

Overview

Package skunk is a thin wrapper for NewRelic's plugin API. It provides a small daemon type that can run as a goroutine and periodically send requests to NewRelic's API with metrics for any components you record metrics for.

Index

• Constants
• Variables
• type Agent
  • func New(version, apiKey string) (*Agent, error)
  • func NewWithRep(apiKey string, rep AgentRep) (agent *Agent, err error)
  • func (a *Agent) Close() error
  • func (a *Agent) Component(name, guid string) (*Component, error)
  • func (a *Agent) Err() (err error)
  • func (a *Agent) Start()
• type AgentRep
• type Body
• type Component
  • func (c *Component) AddMetric(name string, value float64)
  • func (c *Component) MergeMetric(name string, value Metric)
  • func (c *Component) MergeMetrics(metrics Metrics)
• type Error
  • func (e *Error) Error() string
• type Metric
• type Metrics
  • func (m Metrics) AddFloat(name string, val float64)
  • func (m Metrics) AddMetric(name string, val Metric)
  • func (m Metrics) MergeMetrics(metrics Metrics)
• type RangeMetric
  • func (r RangeMetric) Add(value float64) Metric
  • func (r RangeMetric) Merge(value Metric) Metric
• type ScalarMetric
  • func (s ScalarMetric) Add(value float64) Metric
  • func (s ScalarMetric) MarshalJSON() ([]byte, error)
  • func (s ScalarMetric) Merge(value Metric) Metric
• type Seconds
  • func (s Seconds) MarshalJSON() ([]byte, error)

Constants

const (
	MinuteCycle   = time.Minute
	HalfHourCycle = time.Minute * 30
	HourCycle     = time.Hour
)

MinuteCycle, QuarterHourCycle, HalfHourCycle, and HourCycle all represent useful reporting cycles for an agent. Other cycles are permitted, provide they would not violate the two-POSTs-per-minute limit on NewRelic APIs.

const (
	ErrNameTooLong int = 1 + iota
	ErrNoName
	ErrNoGUID

	ErrNoAPIKey
	ErrNoHost
	ErrNoVersion

	ErrNotRunning
	ErrNilOpReceived
	ErrEmptyPayload

	ErrBadPayload
	ErrForbidden
	ErrBadRequest
	ErrBodyTooLarge
	ErrEncodingJSON
)

Variables

var NewRelicAPI = `https://platform-api.newrelic.com/platform/v1/metrics`

NewRelicAPI is the URL to POST NewRelic metrics data to. This may be altered to change the default endpoint of new agents. Already-initialized agents do not use this.

Types

type Agent

type Agent struct {
	// Initialization fields -- these may not change after Start is called. Prior to calling Start, you may tweak
	// them to your heart's content.
	Cycle      time.Duration
	Client     *http.Client
	Log        io.Writer
	LogMetrics bool
	// contains filtered or unexported fields
}

func New

func New(version, apiKey string) (*Agent, error)

func NewWithRep

func NewWithRep(apiKey string, rep AgentRep) (agent *Agent, err error)

func (*Agent) Close

func (a *Agent) Close() error

Close kills the agent's runloop and makes it completely inert. Using the agent afterward will result in a panic. Any error held by the agent prior to shutdown is returned.

When calling Close, you must ensure that the agent is no longer in use and will not be used by any goroutine after Close is called.

func (*Agent) Component

func (a *Agent) Component(name, guid string) (*Component, error)

Component gets a component with the given name and GUID from the Agent. If no such component exists, then a new one is allocated and it is returned. No tests are done to ensure that components with the same name but a different GUID or vice versa are allocated, so it is possible to end up with potentially inconsistent data.

func (*Agent) Err

func (a *Agent) Err() (err error)

func (*Agent) Start

func (a *Agent) Start()

type AgentRep

type AgentRep struct {
	Host string `json:"host"`
	// PID zero is treated as an erroneous/nonexistent PID. If you're shoving NewRelic into a Go-based scheduler in
	// the kernel, I guess you could open an issue for this. Otherwise, this seems reasonable to me.
	PID     int    `json:"pid,omitempty"`
	Version string `json:"version"`
}

AgentRep describes a NewRelic agent.

type Body

type Body struct {
	Agent      AgentRep     `json:"agent"`
	Components []*Component `json:"components"`
}

Body represents the POSTed body of a NewRelic plugin's metrics data.

type Component

type Component struct {
	Name string `json:"name"`
	GUID string `json:"guid"`
	// Duration is the time elapsed, in seconds, for this snapshot of the component. The duration is rounded to the
	// nearest second. This is only used when constructing a payload using a copy of a Component.
	Duration Seconds `json:"duration"`
	Metrics  Metrics `json:"metrics"`
	// contains filtered or unexported fields
}

Component describes a component in a NewRelic agent. It must contain a minimum of at least one metric, otherwise the component is culled from its parent Body before constructing a JSON payload. All fields of the Component are read-only once initialized.

func (*Component) AddMetric

func (c *Component) AddMetric(name string, value float64)

AddMetric adds a single metric to the Component. If the metric already exists by name in the Component, the value is added to the existing metric, otherwise the metric is added as a ScalarMetric.

func (*Component) MergeMetric

func (c *Component) MergeMetric(name string, value Metric)

AddMetric adds a single metric to the Component. If the metric already exists by name in the Component, the value is added to the existing metric, otherwise the metric is added as a ScalarMetric.

func (*Component) MergeMetrics

func (c *Component) MergeMetrics(metrics Metrics)

MergeMetrics merges a Metrics set into the component's metrics. This can be used to do batch updates of metrics if you're sending lots of metrics out and the agent is blocking goroutines due to high-frequency parallel updates.

type Error

type Error struct {
	Msg  string // A message describing the error
	Code int    // A unique number identifying the particular error
	Err  error  // Any inner error
}

Error is any error internal to skunk or an error encapsulated by skunk.

func (*Error) Error

func (e *Error) Error() string

type Metric

type Metric interface {
	Add(value float64) Metric
	Merge(Metric) Metric
}

Metric describes any metric that can have an additional value added to it. All metrics must be marshallable as JSON, but are not required to implement MarshalJSON (e.g., RangeMetric).

The Add method of a Metric is used to get the result of adding an additional value to a metric. Metrics themselves should be considered immutable, so the result must be a new Metric.

This shouldn't be implemented by other libraries.

type Metrics

type Metrics map[string]Metric

Metrics is a map of NewRelic metric names to values. It provides a couple convenience methods for building up merge-able metrics.

func (Metrics) AddFloat

func (m Metrics) AddFloat(name string, val float64)

AddFloat adds a single float metric (as a ScalarMetric) to the Metrics map.

func (Metrics) AddMetric

func (m Metrics) AddMetric(name string, val Metric)

AddMetric merges a Metric into the Metrics map. Merges always happen by merging the existing value into the new metric, rather than vice versa, to give externally-defined Metrics an opportunity to perform the merge (since otherwise a RangeMetric, for example, will just call this anyway).

func (Metrics) MergeMetrics

func (m Metrics) MergeMetrics(metrics Metrics)

MergeMetrics merges all Metrics in the given map into m.

type RangeMetric

type RangeMetric struct {
	Total float64 `json:"total"`
	Count int     `json:"count"`
	Min   float64 `json:"min"`
	Max   float64 `json:"max"`
	// Square is the sum of squares of all values recorded for the metric. This is simply A₁² + A₂² + Aₙ² where A is
	// the set of numbers recorded for this metric.
	Square float64 `json:"sum_of_squares"`
}

RangeMetric is any metric that covers a range of values. Adding to a RangeMetric produces a new RangeMetric.

func (RangeMetric) Add

func (r RangeMetric) Add(value float64) Metric

func (RangeMetric) Merge

func (r RangeMetric) Merge(value Metric) Metric

type ScalarMetric

type ScalarMetric float64

ScalarMetric is any singular metric that does not cover a range a values. Adding to a ScalarMetric produces a RangeMetric.

func (ScalarMetric) Add

func (s ScalarMetric) Add(value float64) Metric

func (ScalarMetric) MarshalJSON

func (s ScalarMetric) MarshalJSON() ([]byte, error)

func (ScalarMetric) Merge

func (s ScalarMetric) Merge(value Metric) Metric

type Seconds

type Seconds struct{ time.Duration }

Seconds is a convenience wrapper around a time.Duration to allow any duration to be used when describing the duration of components' metrics.

func (Seconds) MarshalJSON

func (s Seconds) MarshalJSON() ([]byte, error)