gorelic

README

GoRelic

New Relic agent for Go runtime. It collect a lot of metrics about scheduler, garbage collector and memory allocator and send them to NewRelic.

Requirements

• Go 1.1 or higher
• github.com/yvasiyarov/gorelic
• github.com/yvasiyarov/newrelic_platform_go
• github.com/yvasiyarov/go-metrics

You have to install manually only first two dependencies. All other dependencies will be installed automatically by Go toolchain.

Installation

go get github.com/yvasiyarov/gorelic

and add to the initialization part of your application following code:

import (
    "github.com/yvasiyarov/gorelic"
)
....

agent := gorelic.NewAgent()
agent.Verbose = true
agent.NewrelicLicense = "YOUR NEWRELIC LICENSE KEY THERE"
agent.Run()

Configuration

• NewrelicLicense - its the only mandatory setting of this agent.
• NewrelicName - component name in NewRelic dashboard. Default value: "Go daemon"
• NewrelicPollInterval - how often metrics will be sent to NewRelic. Default value: 60 seconds
• Verbose - print some usefull for debugging information. Default value: false
• CollectGcStat - should agent collect garbage collector statistic or not. Default value: true
• CollectMemoryStat - should agent collect memory allocator statistic or not. Default value: true
• GCPollInterval - how often should GC statistic collected. Default value: 10 seconds. It has performance impact. For more information, please, see metrics documentation.
• MemoryAllocatorPollInterval - how often should memory allocator statistic collected. Default value: 60 seconds. It has performance impact. For more information, please, read metrics documentation.

Metrics reported by plugin

This agent use functions exposed by runtime or runtime/debug packages to collect most important information about Go runtime.

General metrics

• Runtime/General/NOGoroutines - number of runned go routines, as it reported by NumGoroutine() from runtime package
• Runtime/General/NOCgoCalls - number of runned cgo calls, as it reported by NumCgoCall() from runtime package

Garbage collector metrics

• Runtime/GC/NumberOfGCCalls - Nuber of GC calls, as it reported by ReadGCStats() from runtime/debug
• Runtime/GC/PauseTotalTime - Total pause time diring GC calls, as it reported by ReadGCStats() from runtime/debug (in nanoseconds)
• Runtime/GC/GCTime/Max - max GC time
• Runtime/GC/GCTime/Min - min GC time
• Runtime/GC/GCTime/Mean - GC mean time
• Runtime/GC/GCTime/Percentile95 - 95% percentile of GC time

All this metrics are measured in nanoseconds. Last 4 of them can be inaccurate if GC called more often then once in GCPollInterval. If in your workload GC is called more often - you can consider decreasing value of GCPollInterval. But be carefull, ReadGCStats() blocks mheap, so its not good idea to set GCPollInterval to very low values.

Memory allocator

• Component/Runtime/Memory/SysMem/Total - number of bytes/minute allocated from OS totally.
• Component/Runtime/Memory/SysMem/Stack - number of bytes/minute allocated from OS for stacks.
• Component/Runtime/Memory/SysMem/MSpan - number of bytes/minute allocated from OS for internal MSpan structs.
• Component/Runtime/Memory/SysMem/MCache - number of bytes/minute allocated from OS for internal MCache structs.
• Component/Runtime/Memory/SysMem/Heap - number of bytes/minute allocated from OS for heap.
• Component/Runtime/Memory/SysMem/BuckHash - number of bytes/minute allocated from OS for internal BuckHash structs.
• Component/Runtime/Memory/Operations/NoFrees - number of memory frees per minute
• Component/Runtime/Memory/Operations/NoMallocs - number of memory allocations per minute
• Component/Runtime/Memory/Operations/NoPointerLookups - number of pointer lookups per minute
• Component/Runtime/Memory/InUse/Total - total amount of memory in use
• Component/Runtime/Memory/InUse/Heap - amount of memory in use for heap
• Component/Runtime/Memory/InUse/MCacheInuse - amount of memory in use for MCache internal structures
• Component/Runtime/Memory/InUse/MSpanInuse - amount of memory in use for MSpan internal structures
• Component/Runtime/Memory/InUse/Stack - amount of memory in use for stacks

Process metrics

• Component/Runtime/System/Threads - number of OS threads used
• Runtime/System/FDSize - number of file descriptors, used by process
• Runtime/System/Memory/VmPeakSize - VM max size
• Runtime/System/Memory/VmCurrent - VM current size
• Runtime/System/Memory/RssPeak - max size of resident memory set
• Runtime/System/Memory/RssCurrent - current size of resident memory set

All this metrics collected once in MemoryAllocatorPollInterval. In order to collect this statistic agent use ReadMemStats() routine. This routine calls stoptheworld() internally and it block everything. So, please, consider this when you change MemoryAllocatorPollInterval value.

TODO

• Collect more CPU metrics
• Collect per-size allocation statistic
• Collect user defined metrics
• Monkey-patching for web applications

Documentation

Overview

Package gorelic is an New Relic agent implementation for Go runtime. It collect a lot of metrics about Go scheduler, garbage collector and memory allocator and send them to NewRelic.

Index

• Constants
• type Agent
  • func NewAgent() *Agent
  • func (agent *Agent) Debug(msg string)
  • func (agent *Agent) Run() error
• type BaseGoMetrica
  • func (metrica *BaseGoMetrica) GetName() string
  • func (metrica *BaseGoMetrica) GetUnits() string
• type GaugeIncMetrica
  • func (metrica *GaugeIncMetrica) GetValue() (float64, error)
• type GaugeMetrica
  • func (metrica *GaugeMetrica) GetValue() (float64, error)
• type GoMetricaDataSource
  • func NewGCMetricaDataSource(pollInterval int) GoMetricaDataSource
  • func NewMemoryMetricaDataSource(pollInterval int) GoMetricaDataSource
  • func (ds GoMetricaDataSource) GetGaugeValue(key string) (float64, error)
  • func (ds GoMetricaDataSource) GetHistogramValue(key string, statFunction int, percentile float64) (float64, error)
• type HistogramMetrica
  • func (metrica *HistogramMetrica) GetValue() (float64, error)
• type ISystemMetricaDataSource
  • func NewSystemMetricaDataSource() ISystemMetricaDataSource
• type LinuxSystemMetricaDataSource
  • func (ds *LinuxSystemMetricaDataSource) GetValue(key string) (float64, error)
• type NOCgoCallsMetrica
  • func (metrica *NOCgoCallsMetrica) GetName() string
  • func (metrica *NOCgoCallsMetrica) GetUnits() string
  • func (metrica *NOCgoCallsMetrica) GetValue() (float64, error)
• type NOGoroutinesMetrica
  • func (metrica *NOGoroutinesMetrica) GetName() string
  • func (metrica *NOGoroutinesMetrica) GetUnits() string
  • func (metrica *NOGoroutinesMetrica) GetValue() (float64, error)
• type SystemMetrica
  • func (metrica *SystemMetrica) GetName() string
  • func (metrica *SystemMetrica) GetUnits() string
  • func (metrica *SystemMetrica) GetValue() (float64, error)
• type SystemMetricaDataSource
  • func (ds *SystemMetricaDataSource) GetValue(key string) (float64, error)

Constants

const (
	// Send data to newrelic every 60 seconds
	NEWRELIC_POLL_INTERVAL = 60
	// Get garbage collector run statistic every 10 seconds
	// During GC stat pooling - mheap will be locked, so be carefull changing this value
	GC_POLL_INTERVAL_IN_SECONDS = 10
	// Get memory allocator statistic every 60 seconds
	// During this process stoptheword() is called, so be carefull changing this value
	MEMORY_ALLOCATOR_POLL_INTERVAL_IN_SECONDS = 60

	AGENT_GUID    = "com.github.yvasiyarov.GoRelic"
	AGENT_VERSION = "0.0.4"
	AGENT_NAME    = "Go daemon"
)

const (
	HISTOGRAM_MIN = iota
	HISTOGRAM_MAX
	HISTOGRAM_MEAN
	HISTOGRAM_PERCENTILE
	HISTOGRAM_STD_DEV
	HISTOGRAM_VARIANCE
	NO_HISTOGRAM_FUNCTIONS
)

const LINUX_SYSTEM_QUERY_INTERVAL = 60

Types

type Agent

type Agent struct {
	NewrelicName                string
	NewrelicLicense             string
	NewrelicPollInterval        int
	Verbose                     bool
	CollectGcStat               bool
	CollectMemoryStat           bool
	GCPollInterval              int
	MemoryAllocatorPollInterval int
	AgentGUID                   string
	AgentVersion                string
	// contains filtered or unexported fields
}

func NewAgent

func NewAgent() *Agent

func (*Agent) Debug

func (agent *Agent) Debug(msg string)

func (*Agent) Run

func (agent *Agent) Run() error

type BaseGoMetrica

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

func (*BaseGoMetrica) GetName

func (metrica *BaseGoMetrica) GetName() string

func (*BaseGoMetrica) GetUnits

func (metrica *BaseGoMetrica) GetUnits() string

type GaugeIncMetrica

type GaugeIncMetrica struct {
	*BaseGoMetrica
	// contains filtered or unexported fields
}

func (*GaugeIncMetrica) GetValue

func (metrica *GaugeIncMetrica) GetValue() (float64, error)

type GaugeMetrica

type GaugeMetrica struct {
	*BaseGoMetrica
}

func (*GaugeMetrica) GetValue

func (metrica *GaugeMetrica) GetValue() (float64, error)

type GoMetricaDataSource

type GoMetricaDataSource struct {
	metrics.Registry
}

func NewGCMetricaDataSource

func NewGCMetricaDataSource(pollInterval int) GoMetricaDataSource

func NewMemoryMetricaDataSource

func NewMemoryMetricaDataSource(pollInterval int) GoMetricaDataSource

func (GoMetricaDataSource) GetGaugeValue

func (ds GoMetricaDataSource) GetGaugeValue(key string) (float64, error)

func (GoMetricaDataSource) GetHistogramValue

func (ds GoMetricaDataSource) GetHistogramValue(key string, statFunction int, percentile float64) (float64, error)

type HistogramMetrica

type HistogramMetrica struct {
	*BaseGoMetrica
	// contains filtered or unexported fields
}

func (*HistogramMetrica) GetValue

func (metrica *HistogramMetrica) GetValue() (float64, error)

type ISystemMetricaDataSource

type ISystemMetricaDataSource interface {
	GetValue(key string) (float64, error)
}

OS specific metrics data source interface

func NewSystemMetricaDataSource

func NewSystemMetricaDataSource() ISystemMetricaDataSource

ISystemMetricaDataSource fabrica

type LinuxSystemMetricaDataSource

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

Linux OS implementation of ISystemMetricaDataSource

func (*LinuxSystemMetricaDataSource) GetValue

func (ds *LinuxSystemMetricaDataSource) GetValue(key string) (float64, error)

type NOCgoCallsMetrica

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

Number of CGO calls metrica

func (*NOCgoCallsMetrica) GetName

func (metrica *NOCgoCallsMetrica) GetName() string

func (*NOCgoCallsMetrica) GetUnits

func (metrica *NOCgoCallsMetrica) GetUnits() string

func (*NOCgoCallsMetrica) GetValue

func (metrica *NOCgoCallsMetrica) GetValue() (float64, error)

type NOGoroutinesMetrica

type NOGoroutinesMetrica struct{}

Number of goroutines metrica

func (*NOGoroutinesMetrica) GetName

func (metrica *NOGoroutinesMetrica) GetName() string

func (*NOGoroutinesMetrica) GetUnits

func (metrica *NOGoroutinesMetrica) GetUnits() string

func (*NOGoroutinesMetrica) GetValue

func (metrica *NOGoroutinesMetrica) GetValue() (float64, error)

type SystemMetrica

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

OS specific metrica

func (*SystemMetrica) GetName

func (metrica *SystemMetrica) GetName() string

func (*SystemMetrica) GetUnits

func (metrica *SystemMetrica) GetUnits() string

func (*SystemMetrica) GetValue

func (metrica *SystemMetrica) GetValue() (float64, error)

type SystemMetricaDataSource

type SystemMetricaDataSource struct{}

Default implementation of ISystemMetricaDataSource. Just return an error

func (*SystemMetricaDataSource) GetValue

func (ds *SystemMetricaDataSource) GetValue(key string) (float64, error)