newrelic

README

newrelic: Go NewRelic plugin API client

newrelic is an embeddable client for implementing custom NewRelic plugins. It is aided and inpired by yvasiyarov's newrelic_platform_go package.

Installation

go get github.com/neocortical/newrelic

Use

import (
	"runtime"
	"time"

	"github.com/neocortical/newrelic"
)

func main() {
	client := newrelic.New("abc123") // license key goes here
	myplugin := &Plugin{
		Name: "My Plugin",
		GUID: "com.example.newrelic.myplugin",
	}
	client.AddPlugin(myplugin)

	// the easiest way to add a metric is to use a closure
	metric := newrelic.NewMetric("MyApp/Total CGO Calls",
		func() (float64, error) { return float64(runtime.NumCgoCall()), nil })
	plugin.AddMetric()

	// call run after doing all plugin config
	client.Run()

	// main application code here..
	for {
		time.Sleep(time.Minute)
	}
}

Advanced Features

Set log levels and custom log destination

newrelic.LogLevel = newrelic.LogAll
newrelic.Logger = myAwesomeLogger // standard library logger

Use an HTTP proxy to send data to NewRelic

proxy := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(myProxyUrl)}}
client := newrelic.New("abc123")
client.HTTPClient = proxy

Implementation Notes

The NewRelic plugin API reference can be found here. There is some naming confusion in the API that can throw people off. Namely, when crafting API requests, the term components is used when plugins would be more accurate. Additionally, in the reference, the term Agent refers to both the code interacting with the API and the host/process information sent in requests.

When writing this package, the term Plugin is used exclusively to refer to plugins, and the term Client is used to refer to the "agent" that sends data to NewRelic. The objects that model JSON requests are completely separated from business objects to keep things clear.

Documentation

Overview

package newrelic is an client for NewRelic's plugin API.

Simple usage:

import (
	"runtime"
	"time"

	"github.com/neocortical/newrelic"
)

func main() {
	client := newrelic.New("abc123") // license key goes here
	myplugin := &Plugin{
		Name: "My Plugin",
		GUID: "com.example.newrelic.myplugin",
	}
	client.AddPlugin(myplugin)

	// the easiest way to add a metric is to use a closure
	metric := newrelic.NewMetric("MyApp/Total CGO Calls",
		func() (float64, error) { return float64(runtime.NumCgoCall()), nil })
	plugin.AddMetric()

	// call run after doing all plugin config
	client.Run()

	// main application code here..
	for {
		time.Sleep(time.Minute)
	}
}

Index

• Constants
• Variables
• func Log(level LoggingLevel, format string, a ...interface{})
• type Client
  • func New(license string) *Client
  • func (c *Client) AddPlugin(p *Plugin)
  • func (c *Client) Run()
• type CompositeError
  • func (ce CompositeError) Accumulate(err error) CompositeError
  • func (ce CompositeError) Error() string
• type LoggingLevel
• type Metric
  • func NewMetric(name, units string, pollFn func() (float64, error)) Metric
• type Plugin
  • func (p *Plugin) AddMetric(metric Metric)

Constants

const (
	// DefaultPollInterval is the recommended poll interval for NewRelic plugins
	DefaultPollInterval = time.Minute
)

Variables

var LogLevel = LogError

LogLevel can be set globally to tune logging levels

var Logger = l.New(os.Stderr, "newrelic", l.LstdFlags)

Logger is the logger used by this package. Set to a custom logger if needed.

Functions

func Log

func Log(level LoggingLevel, format string, a ...interface{})

Log a message through the newrelic package

Types

type Client

type Client struct {
	License      string
	PollInterval time.Duration
	Plugins      []*Plugin

	// HTTPClient is exposed to allow users to configure proxies, etc.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

Client encapsulates a NewRelic plugin client and all the plugins it reports

func New

func New(license string) *Client

New creates a new Client with the given license

func (*Client) AddPlugin

func (c *Client) AddPlugin(p *Plugin)

AddPlugin appends a plugin to a clients list of plugins. A plugin is a "component" in the API call and can be configured (with a unique GUID) in the NewRelic UI.

func (*Client) Run

func (c *Client) Run()

Run starts the NewRelic client asynchronously. Do not alter the configuration of plugins after starting the client, as this creates race conditions.

type CompositeError

type CompositeError []error

CompositeError accumulates errors from calling metric.Poll(). These errors are logged but otherwise ignored so that functioning metrics may still be collected.

func (CompositeError) Accumulate

func (ce CompositeError) Accumulate(err error) CompositeError

Accumulate errors into a single CompositeError

func (CompositeError) Error

func (ce CompositeError) Error() string

Error implements the error interface.

type LoggingLevel

type LoggingLevel int

LoggingLevel enumerates package log levels

const (
	// LogAll logs verbosely
	LogAll LoggingLevel = 0
	// LogDebug logs debug or above
	LogDebug LoggingLevel = 20
	// LogInfo logs informational or above
	LogInfo LoggingLevel = 30
	// LogError only logs errors
	LogError LoggingLevel = 50
	// LogNone makes the package silent
	LogNone LoggingLevel = 100
)

type Metric

type Metric interface {
	Name() string
	Units() string
	Poll() (float64, error)
}

Metric describes the interface for a metric

func NewMetric

func NewMetric(name, units string, pollFn func() (float64, error)) Metric

NewMetric creates a new metric definition using a closure

type Plugin

type Plugin struct {
	Name string
	GUID string
	// contains filtered or unexported fields
}

Plugin encapsulates all data and state for a plug-in (AKA Component)

func (*Plugin) AddMetric

func (p *Plugin) AddMetric(metric Metric)

AddMetric adds a new metric definition to the plugin/component