newrelic

README

NewRelic Go Agent

A small convenience layer that sits on top of newrelic-go-agent, to make it easy to create transactions for NewRelic in Go.

Caveats

This is alpha software. It has not been tested in a production environment, or any environment for that matter.

Installing

You'll need to install the nr_agent_sdk first.

This package will only work on linux platforms. It is also disabled by default. To enable it, use the build flag newrelic_enabled:

go build -tags newrelic_enabled ./...

Example Usage

See ./example/main.go for a more complete example.

import "github.com/remind101/newrelic"

func main() {
    newrelic.Init("newrelic app name", "newrelic license key")
    tx := newrelic.NewTx("/my/transaction/name")
    tx.Start()
    defer tx.End()

    // Add a segment
    tx.StartGeneric("middleware")
    // Do some middleware stuff...
    tx.EndSegment()
}

Using with an http server

This packages works well as an httpx middleware.

Here is an example using httpx, a context aware http handler.

    r := httpx.NewRouter()

    r.Handle("/articles", &ArticlesHandler{}).Methods("GET")
    r.Handle("/articles/{id}", &ArticleHandler{}).Methods("GET")

    var h httpx.Handler

    // Add NewRelic tracing.
    h = middleware.NewRelicTracing(r, r, &newrelic.NRTxTracer{})

    // Wrap the route in middleware to add a context.Context.
    h = middleware.BackgroundContext(h)

    http.ListenAndServe(":8080", h)

The above example will create web transactions named GET "/articles" and GET "/articles/{id}".

Documentation

Overview

No op implementation for non linux platforms (new relix agent sdk only support linux right now)

Index

• Variables
• func Init(app, key string)
• func NewBackgroundTx(name string, category string) *tx
• func NewRequestTx(name string, url string) *tx
• func NewTx(name string) *tx
• func RecordMetrics(interval time.Duration)
• func RecordMetricsWithRecorder(r Recorder)
• func WithTx(ctx context.Context, t Tx) context.Context
• type NRTxReporter
  • func (r *NRTxReporter) ReportCustomMetric(name string, value float64) (int, error)
  • func (r *NRTxReporter) ReportError(txnID int64, exceptionType, errorMessage, stackTrace, stackFrameDelim string) (int, error)
• type NRTxTracer
  • func (t *NRTxTracer) BeginDatastoreSegment(txnID, parentID int64, table, operation, sql, rollupName string) (int64, error)
  • func (t *NRTxTracer) BeginExternalSegment(txnID, parentID int64, host, name string) (int64, error)
  • func (t *NRTxTracer) BeginGenericSegment(txnID, parentID int64, name string) (int64, error)
  • func (t *NRTxTracer) BeginTransaction() (int64, error)
  • func (t *NRTxTracer) EndSegment(txnID, parentID int64) error
  • func (t *NRTxTracer) EndTransaction(txnID int64) error
  • func (t *NRTxTracer) SetTransactionCategory(txnID int64, category string) error
  • func (t *NRTxTracer) SetTransactionName(txnID int64, name string) error
  • func (t *NRTxTracer) SetTransactionRequestURL(txnID int64, url string) error
  • func (t *NRTxTracer) SetTransactionType(txnID int64, txnType TransactionType) error
• type Recorder
• type SegmentStack
  • func NewSegmentStack() *SegmentStack
  • func (s *SegmentStack) Len() int
  • func (s *SegmentStack) Peek() int64
  • func (s *SegmentStack) Pop() (int64, bool)
  • func (s *SegmentStack) Push(id int64)
• type Trace
  • func TraceDatastore(ctx context.Context, table, operation, sql, rollupName string) *Trace
  • func TraceExternal(ctx context.Context, host, name string) *Trace
  • func TraceFunc(ctx context.Context) *Trace
  • func TraceGeneric(ctx context.Context, name string) *Trace
  • func TraceRequest(ctx context.Context, name string, req *http.Request) (context.Context, *Trace)
  • func (t *Trace) Done()
  • func (t *Trace) Err() error
• type TransactionType
• type Tx
  • func FromContext(ctx context.Context) (Tx, bool)
• type TxReporter
• type TxTracer

Variables

var ErrTxAlreadyStarted = errors.New("transaction already started")

Functions

func Init

func Init(app, key string)

func NewBackgroundTx

func NewBackgroundTx(name string, category string) *tx

NewBackgroundTx returns a new background transaction

func NewRequestTx

func NewRequestTx(name string, url string) *tx

NewRequestTx returns a new transaction with a request url.

func NewTx

func NewTx(name string) *tx

NewTx returns a new transaction.

func RecordMetrics

func RecordMetrics(interval time.Duration)

RecordMetrics records metrics with the default metric recorder.

func RecordMetricsWithRecorder

func RecordMetricsWithRecorder(r Recorder)

RecordMetricsWithRecorder records metrics with the given recorder.

func WithTx

func WithTx(ctx context.Context, t Tx) context.Context

WithTx inserts a newrelic.Tx into the provided context.

Types

type NRTxReporter

type NRTxReporter struct{}

func (*NRTxReporter) ReportCustomMetric

func (r *NRTxReporter) ReportCustomMetric(name string, value float64) (int, error)

func (*NRTxReporter) ReportError

func (r *NRTxReporter) ReportError(txnID int64, exceptionType, errorMessage, stackTrace, stackFrameDelim string) (int, error)

type NRTxTracer

type NRTxTracer struct{}

func (*NRTxTracer) BeginDatastoreSegment

func (t *NRTxTracer) BeginDatastoreSegment(txnID, parentID int64, table, operation, sql, rollupName string) (int64, error)

func (*NRTxTracer) BeginExternalSegment

func (t *NRTxTracer) BeginExternalSegment(txnID, parentID int64, host, name string) (int64, error)

func (*NRTxTracer) BeginGenericSegment

func (t *NRTxTracer) BeginGenericSegment(txnID, parentID int64, name string) (int64, error)

func (*NRTxTracer) BeginTransaction

func (t *NRTxTracer) BeginTransaction() (int64, error)

func (*NRTxTracer) EndSegment

func (t *NRTxTracer) EndSegment(txnID, parentID int64) error

func (*NRTxTracer) EndTransaction

func (t *NRTxTracer) EndTransaction(txnID int64) error

func (*NRTxTracer) SetTransactionCategory

func (t *NRTxTracer) SetTransactionCategory(txnID int64, category string) error

func (*NRTxTracer) SetTransactionName

func (t *NRTxTracer) SetTransactionName(txnID int64, name string) error

func (*NRTxTracer) SetTransactionRequestURL

func (t *NRTxTracer) SetTransactionRequestURL(txnID int64, url string) error

func (*NRTxTracer) SetTransactionType

func (t *NRTxTracer) SetTransactionType(txnID int64, txnType TransactionType) error

type Recorder

type Recorder interface {
	Interval() time.Duration
	Record() error
}

Recorder handles metrics recording.

type SegmentStack

type SegmentStack struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func NewSegmentStack

func NewSegmentStack() *SegmentStack

func (*SegmentStack) Len

func (s *SegmentStack) Len() int

Len returns the length of the stack.

func (*SegmentStack) Peek

func (s *SegmentStack) Peek() int64

Peek returns id from the top of the stack. It returns rootSegment if the stack is empty.

func (*SegmentStack) Pop

func (s *SegmentStack) Pop() (int64, bool)

Pop pops a segment id off of the segment stack. It returns false if the stack is empty.

func (*SegmentStack) Push

func (s *SegmentStack) Push(id int64)

Push pushes a segment id onto the segment stack.

type Trace

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

func TraceDatastore

func TraceDatastore(ctx context.Context, table, operation, sql, rollupName string) *Trace

TraceDatastore adds a datastore segment to the newrelic transaction, if one exists in the context.

func TraceExternal

func TraceExternal(ctx context.Context, host, name string) *Trace

TraceExternal adds an external segment to the newrelic transaction, if one exists in the context.

func TraceFunc

func TraceFunc(ctx context.Context) *Trace

TraceFunc adds a generic segment, autodetecting the function name with runtime.Caller().

func TraceGeneric

func TraceGeneric(ctx context.Context, name string) *Trace

TraceGeneric adds a generic segment to the newrelic transaction, if one exists in the context.

func TraceRequest

func TraceRequest(ctx context.Context, name string, req *http.Request) (context.Context, *Trace)

TraceReqest traces an http request. It returns a new context with the transaction included in it, and a trace object.

Usage:

ctx, t := TraceRequest(ctx, name, req)
defer t.Done()

func (*Trace) Done

func (t *Trace) Done()

func (*Trace) Err

func (t *Trace) Err() error

type TransactionType

type TransactionType int

const (
	WebTransaction TransactionType = iota
	OtherTransaction
)

type Tx

type Tx interface {
	Start() error
	End() error
	StartGeneric(name string) error
	StartDatastore(table, operation, sql, rollupName string) error
	StartExternal(host, name string) error
	EndSegment() error
	ReportError(exceptionType, errorMessage, stackTrace, stackFrameDelim string) error
}

Tx represents a transaction.

func FromContext

func FromContext(ctx context.Context) (Tx, bool)

FromContext returns a newrelic.Tx from the context.

type TxReporter

type TxReporter interface {
	ReportError(txnID int64, exceptionType, errorMessage, stackTrace, stackFrameDelim string) (int, error)
	ReportCustomMetric(name string, value float64) (int, error)
}

TxReporter reports the first error that occured during a transaction.

type TxTracer

type TxTracer interface {
	BeginTransaction() (int64, error)
	EndTransaction(txnID int64) error

	SetTransactionName(txnID int64, name string) error
	SetTransactionRequestURL(txnID int64, url string) error
	SetTransactionType(txnID int64, txnType TransactionType) error
	SetTransactionCategory(txnID int64, category string) error

	BeginGenericSegment(txnID int64, parentID int64, name string) (int64, error)
	BeginDatastoreSegment(txnID int64, parentID int64, table string, operation string, sql string, rollupName string) (int64, error)
	BeginExternalSegment(txnID int64, parentID int64, host string, name string) (int64, error)
	EndSegment(txnID int64, parentID int64) error
}

TxTracer handles transaction tracing.