README
¶
SimpleRelic
SimpleRelic is a Go reporting library sending http metrics to NewRelic. It is designed with simplicity in mind i.e. to add a new metric you only have to implement a struct with two functions. There are currently three default metrics.
Default metrics:
- number of requests per endpoint
- percentage of 4xx and 5xx errors per endpoint
- response time per endpoint
The library is consisting of two parts:
- sending metrics to NewRelic Plugin API
- updating the HTTP metrics (on every request)
Metrics will be collected and sent to NewRelic every 60 seconds by a separate go routine. Updating the HTTP metrics requires that you wrap your request handler with a function that updates the metrics (see example below).
Ideally you will create your own dashboards and graphs in NewRelic (see the Custom NewRelic Plugin at the bottom of the page). Example of a dashboard you can see here.
Basic usage
Create a default reporter that uses default metrics.
reporter, err := simplerelic.InitDefaultReporter(cfg.NewRelicName, cfg.NewRelicKey, cfg.DebugMode)
if err != nil {
// handle error
}
reporter.Start()
The code above does the initialisation of the reporter. In order to track and update the http metrics, you need to wrap your http request handler function with a function that updates the metrics. In case you're using Gin framework you can use the snippet below, otherwise adopt it accordingly.
func makeHandler(fn func(*gin.Context), endpointName string) gin.HandlerFunc {
if simplerelic.Engine == nil {
// handle error
}
return func(c *gin.Context) {
params := simplerelic.DefaultReqParams(endpointName)
fn(c)
simplerelic.CollectParamsOnReqEnd(params, c.Writer.Status())
simplerelic.UpdateMetricsOnReqEnd(params)
}
}
In the example above parameter fn is your original handler. Parameter endpointName is required by default metrics to identify the
endpoint you are reporting the values for. Metrics can take additional parameters passed in a params variable (map[string]interface{}).
The parameters for default metrics are mostly set by DefaultReqParams function except for statusCode that needs to be set later
in the request lifetime. The metric values are updated by UpdateMetricsOnReqEnd function.
Add an user defined metric
User defined metrics need to implement AppMetric interface.
type AppMetric interface {
// Update all the values that will be reported (or be used in calculation).
// For http metrics called on every request (for example in gin middleware)
Update(params map[string]interface{}) error
// ValueMap extracts all values from AppMetric data structures
// to be reported to NewRelic.
// A single AppMetric can produce multiple metrics as perceived by NewRelic
// Consult NewRelic plugin API naming guidelines
// before creating a new metric.
//
// Note that this function is also responsible for clearing the values
// after they have been reported.
ValueMap() map[string]float32
}
For example of a metric take a look at ReqPerEndpoint in metrics.go.
After you define your new metric you need to add it to the reporter.
reporter, err := simplerelic.InitDefaultReporter(cfg.NewRelicName, cfg.NewRelicKey, cfg.DebugMode)
if err != nil {
// handle error
}
reporter.AddMetrics(NewUserDefinedMetric())
Custom NewRelic plugin
In case you add your own metrics and want to build dashboards and graphs for them, you need to create your own NewRelic plugin. To report metrics to your own plugin you just need to set the GUID (before creating the reporter).
simplerelic.Guid = "com.example.simplerelic"
Documentation
¶
Index ¶
- Variables
- func CollectParamsOnReqEnd(params map[string]interface{}, statusCode int) map[string]interface{}
- func DefaultReqParams(endpointName string) map[string]interface{}
- func UpdateMetricsOnReqEnd(params map[string]interface{})
- type AppMetric
- type ErrorRatePerEndpoint
- type Reporter
- type ReqPerEndpoint
- type ResponseTimePerEndpoint
- type StandardMetric
Constants ¶
This section is empty.
Variables ¶
var ( // Log is a logger used in the package Log *log.Logger // NewRelic GUID for creating the NewRelic plugin Guid string )
Functions ¶
func CollectParamsOnReqEnd ¶
CollectParamsOnReqEnd populates params map with additional data available when the request processing is already done e.g. http response status code
func DefaultReqParams ¶
DefaultReqParams creates and populates request parameters map to be used by default metrics Called in the beginning of each request
func UpdateMetricsOnReqEnd ¶
func UpdateMetricsOnReqEnd(params map[string]interface{})
UpdateMetricsOnReqEnd updates all defined metrics in the end of each request
Types ¶
type AppMetric ¶
type AppMetric interface {
// Update all the values that will be reported (or be used in calculation).
// For http metrics called on every request (for example in gin middleware)
Update(params map[string]interface{}) error
// ValueMap extracts all values from AppMetric data structures
// to be reported to NewRelic.
// A single AppMetric can produce multiple metrics as perceived by NewRelic
// Consult NewRelic plugin API naming guidelines
// before creating a new metric.
//
// Note that this function is also responsible for clearing the values
// after they have been reported.
ValueMap() map[string]float32
}
AppMetric is an interface for metrics reported to NewRelic
type ErrorRatePerEndpoint ¶
type ErrorRatePerEndpoint struct {
*StandardMetric
// contains filtered or unexported fields
}
ErrorRatePerEndpoint holds the percentage of error requests per endpoint
func NewErrorRatePerEndpoint ¶
func NewErrorRatePerEndpoint() *ErrorRatePerEndpoint
NewErrorRatePerEndpoint creates new POEPerEndpoint metric
func (*ErrorRatePerEndpoint) Update ¶
func (m *ErrorRatePerEndpoint) Update(params map[string]interface{}) error
Update the metric values
func (*ErrorRatePerEndpoint) ValueMap ¶
func (m *ErrorRatePerEndpoint) ValueMap() map[string]float32
ValueMap extract all the metrics to be reported
type Reporter ¶
type Reporter struct {
Metrics []AppMetric
// contains filtered or unexported fields
}
Reporter keeps track of the app metrics and sends them to NewRelic
var ( // Engine reports metrics to NewRelic Engine *Reporter )
func InitDefaultReporter ¶
InitDefaultReporter creates a new reporter and adds standard metrics
func NewReporter ¶
NewReporter creates a new Reporter
type ReqPerEndpoint ¶
type ReqPerEndpoint struct {
*StandardMetric
}
ReqPerEndpoint holds number of requests per endpoint
func NewReqPerEndpoint ¶
func NewReqPerEndpoint() *ReqPerEndpoint
NewReqPerEndpoint creates new ReqPerEndpoint metric
func (*ReqPerEndpoint) Update ¶
func (m *ReqPerEndpoint) Update(params map[string]interface{}) error
Update the metric values
func (*ReqPerEndpoint) ValueMap ¶
func (m *ReqPerEndpoint) ValueMap() map[string]float32
ValueMap extract all the metrics to be reported
type ResponseTimePerEndpoint ¶
type ResponseTimePerEndpoint struct {
*StandardMetric
// contains filtered or unexported fields
}
ResponseTimePerEndpoint tracks the response time per endpoint
func NewResponseTimePerEndpoint ¶
func NewResponseTimePerEndpoint() *ResponseTimePerEndpoint
NewResponseTimePerEndpoint creates new ResponseTimePerEndpoint metric
func (*ResponseTimePerEndpoint) Update ¶
func (m *ResponseTimePerEndpoint) Update(params map[string]interface{}) error
Update the metric values
func (*ResponseTimePerEndpoint) ValueMap ¶
func (m *ResponseTimePerEndpoint) ValueMap() map[string]float32
ValueMap extract all the metrics to be reported
type StandardMetric ¶
type StandardMetric struct {
// contains filtered or unexported fields
}
StandardMetric is a base for metrics dealing with endpoints
Source Files