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

Middleware

If you using Beego, Martini, Revel or Gin framework you can hook up gorelic with your application by using the following middleware:

• https://github.com/yvasiyarov/beego_gorelic
• https://github.com/yvasiyarov/martini_gorelic
• https://github.com/yvasiyarov/gocraft_gorelic
• http://wiki.colar.net/revel_newelic
• https://github.com/jingweno/negroni-gorelic
• https://github.com/brandfolder/gin-gorelic

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
• CollectHTTPStat - should agent collect HTTP metrics. Default value: false
• 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.

HTTP metrics

• throughput (requests per second), calculated for last minute
• mean throughput (requests per second)
• mean response time
• min response time
• max response time
• 75%, 90%, 95% percentiles for response time

In order to collect HTTP metrics, handler functions must be wrapped using WrapHTTPHandlerFunc:

http.HandleFunc("/", agent.WrapHTTPHandlerFunc(handler))

TODO

• Collect per-size allocation statistic
• Collect user defined metrics

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) Run() error
  • func (agent *Agent) WrapHTTPHandler(h http.Handler) http.Handler
  • func (agent *Agent) WrapHTTPHandlerFunc(h tHTTPHandlerFunc) tHTTPHandlerFunc

Constants

const (
	// DefaultNewRelicPollInterval - how often we will report metrics to NewRelic.
	// Recommended values is 60 seconds
	DefaultNewRelicPollInterval = 60

	// DefaultGcPollIntervalInSeconds - how often we will get garbage collector run statistic
	// Default value is - every 10 seconds
	// During GC stat pooling - mheap will be locked, so be carefull changing this value
	DefaultGcPollIntervalInSeconds = 10

	// DefaultMemoryAllocatorPollIntervalInSeconds - how often we will get memory allocator statistic.
	// Default value is - every 60 seconds
	// During this process stoptheword() is called, so be carefull changing this value
	DefaultMemoryAllocatorPollIntervalInSeconds = 60

	//DefaultAgentGuid is plugin ID in NewRelic.
	//You should not change it unless you want to create your own plugin.
	DefaultAgentGuid = "com.github.yvasiyarov.GoRelic"

	//CurrentAgentVersion is plugin version
	CurrentAgentVersion = "0.0.6"

	//DefaultAgentName in NewRelic GUI. You can change it.
	DefaultAgentName = "Go daemon"
)

Types

type Agent

type Agent struct {
	NewrelicName                string
	NewrelicLicense             string
	NewrelicPollInterval        int
	Verbose                     bool
	CollectGcStat               bool
	CollectMemoryStat           bool
	CollectHTTPStat             bool
	GCPollInterval              int
	MemoryAllocatorPollInterval int
	AgentGUID                   string
	AgentVersion                string

	HTTPTimer metrics.Timer
	// contains filtered or unexported fields
}

Agent - is NewRelic agent implementation. Agent start separate go routine which will report data to NewRelic

func NewAgent

func NewAgent() *Agent

NewAgent build new Agent objects.

func (*Agent) Run

func (agent *Agent) Run() error

Run initialize Agent instance and start harvest go routine

func (*Agent) WrapHTTPHandler

func (agent *Agent) WrapHTTPHandler(h http.Handler) http.Handler

WrapHTTPHandler instrument HTTP handler object to collect HTTP metrics

func (*Agent) WrapHTTPHandlerFunc

func (agent *Agent) WrapHTTPHandlerFunc(h tHTTPHandlerFunc) tHTTPHandlerFunc

WrapHTTPHandlerFunc instrument HTTP handler functions to collect HTTP metrics