gorelic

package module
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2019 License: BSD-2-Clause Imports: 13 Imported by: 1

README

GoRelic is deprecated in favour of https://github.com/newrelic/go-agent

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, Kami or Gin framework you can hook up gorelic with your application by using the following middleware:

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
  • CollectHTTPStatuses - should agent collect metrics on HTTP status codes. 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 careful, 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))
Tracing Metrics

You can collect metrics for blocks of code or methods.

func anyMethod() {
  // Trace the whole method.
  t := agent.Tracer.BeginTrace("My traced method")
  defer t.EndTrace()
  
  ...Code here
  
  // Trace a block of code
  agent.Tracer.Trace("block trace", func() {
     .. Code here
  })
}

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

View Source 
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"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Agent 

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

	HTTPTimer          metrics.Timer
	HTTPStatusCounters map[int]metrics.Counter
	Tracer             *Tracer
	CustomMetrics      []newrelic_platform_go.IMetrica

	// All HTTP requests will be done using this client. Change it if you need
	// to use a proxy.
	Client http.Client
	// 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 builds new Agent objects.

func (*Agent) AddCustomMetric added in v0.0.7 

func (agent *Agent) AddCustomMetric(metric newrelic_platform_go.IMetrica)

AddCustomMetric adds metric to be collected periodically with NewrelicPollInterval interval

func (*Agent) Run 

func (agent *Agent) Run() error

Run initialize Agent instance and start harvest go routine

func (*Agent) WrapHTTPHandler added in v0.0.5 

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

WrapHTTPHandler instrument HTTP handler object to collect HTTP metrics

func (*Agent) WrapHTTPHandlerFunc added in v0.0.5 

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

WrapHTTPHandlerFunc instrument HTTP handler functions to collect HTTP metrics

type Trace added in v0.0.7 

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

func (*Trace) EndTrace added in v0.0.7 

func (t *Trace) EndTrace()

type TraceTransaction added in v0.0.7 

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

type Tracer added in v0.0.7 

type Tracer struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func (*Tracer) BeginTrace added in v0.0.7 

func (t *Tracer) BeginTrace(name string) *Trace

func (*Tracer) Trace added in v0.0.7 

func (t *Tracer) Trace(name string, traceFunc func())

Source Files

View all Source files

Directories

Path Synopsis

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.