API Documentationedit

Below we cover the most commonly used parts of the API.

The Go agent is documented using standard godoc. For complete documentation, refer to the documentation at godoc.org/go.elastic.co/apm, or by using the "godoc" tool.

Tracer APIedit

The initial point of contact your application will have with the Go agent is the apm.Tracer type, which provides methods for reporting transactions and errors.

To make instrumentation simpler the Go agent provides a pre-initialized tracer, apm.DefaultTracer. This tracer is always initialized and available for use. This tracer is configured with environment variables; see Configuration for details.

import (
        "go.elastic.co/apm"
)

func main() {
        tracer := apm.DefaultTracer
        ...
}

Transactionsedit

func (*Tracer) StartTransaction(name, type string) *Transactionedit

StartTransaction returns a new Transaction with the specified name and type, and with the start time set to the current time.. If you need to set the timestamp or set the parent trace context, you should use Tracer.StartTransactionOptions.

This method should be called at the beginning of a transaction such as a web or RPC request. e.g.:

transaction := apm.DefaultTracer.StartTransaction("GET /", "request")

Transactions will be grouped by type and name in the Elastic APM UI.

After starting a transaction, you can record a result and add context to further describe the transaction.

transaction.Result = "Success"
transaction.Context.SetTag("region", "us-east-1")

See Contextedit for more details on setting transaction context.

func (*Tracer) StartTransactionOptions(name, type string, opts TransactionOptions) *Transactionedit

StartTransactionOptions is essentially the same as StartTransaction, but also accepts an options struct. This struct allows you to specify the parent trace context and/or the transaction’s start time.

opts := apm.TransactionOptions{
        Start: time.Now(),
        TraceContext: parentTraceContext,
}
transaction := apm.DefaultTracer.StartTransactionOptions("GET /", "request", opts)

func (*Transaction) End()edit

End enqueues the transaction for sending to the Elastic APM server. The Transaction must not be used after this.

The transaction’s duration will be calculated as the amount of time elapsed since the transaction was started until this call. To override this behaviour, the transaction’s Duration field may be set before calling End.

transaction.End()

func (*Transaction) TraceContext() TraceContextedit

TraceContext returns the transaction’s trace context.

func (*Transaction) EnsureParent() SpanIDedit

EnsureParent returns the transaction’s parent span ID, generating and recording one if it did not previously have one.

EnsureParent enables correlation with spans created by the JavaScript Real User Monitoring (RUM) agent for the initial page load. If your backend service generates the HTML page dynamically, you can inject the trace and parent span ID into the page in order to initialize the JavaScript RUM agent, such that the web browser’s page load appears as the root of the trace.

var initialPageTemplate = template.Must(template.New("").Parse(`
<html>
<head>
<script src="elastic-apm-js-base/dist/bundles/elastic-apm-js-base.umd.min.js"></script>
<script>
  elasticApm.init({
    serviceName: '',
    serverUrl: 'http://localhost:8200',
    pageLoadTraceId: {{.TraceContext.Trace}},
    pageLoadSpanId: {{.EnsureParent}},
    pageLoadSampled: {{.Sampled}},
  })
</script>
</head>
<body>...</body>
</html>
`))

func initialPageHandler(w http.ResponseWriter, req *http.Request) {
        err := initialPageTemplate.Execute(w, apm.TransactionFromContext(req.Context()))
        if err != nil {
                ...
        }
}

See the JavaScript RUM agent documentation for more information.

func ContextWithTransaction(context.Context, *Transaction) context.Contextedit

ContextWithTransaction adds the transaction to the context, and returns the resulting context.

The transaction can be retrieved using apm.TransactionFromContext. The context may also be passed into apm.StartSpan, which uses TransactionFromContext under the covers to create a span as a child of the transaction.

func TransactionFromContext(context.Context) *Transactionedit

TransactionFromContext returns a transaction previously stored in the context using apm.ContextWithTransaction, or nil if the context does not contain a transaction.

Spansedit

To describe an activity within a transaction, we create spans. The Go agent has built-in support for generating spans for some activities, such as database queries. You can use the API to report spans specific to your application.

func (*Transaction) StartSpan(name, spanType string, parent *Span) *Spanedit

StartSpan starts and returns a new Span within the transaction, with the specified name, type, and optional parent span, and with the start time set to the current time. If you need to set the timestamp or parent trace context, you should use Transaction.StartSpanOptions.

If the transaction is sampled, then the span’s ID will be set, and its stacktrace will be set if the tracer is configured accordingly. If the transaction is not sampled, then the returned span will be silently discarded when its End method is called. You can avoid any unnecessary computation for these dropped spans by calling the Dropped method.

As a convenience, it is valid to create a span on a nil Transaction; the resulting span will be non-nil and safe for use, but will not be reported to the APM server.

span := tx.StartSpan("SELECT FROM foo", "db.mysql.query", nil)

func (*Transaction) StartSpanOptions(name, spanType string, opts SpanOptions) *Spanedit

StartSpanOptions is essentially the same as StartSpan, but also accepts an options struct. This struct allows you to specify the parent trace context and/or the spans’s start time. If the parent trace context is not specified in the options, then the span will be a direct child of the transaction. Otherwise, the parent trace context should belong to some span descended from the transaction.

opts := apm.SpanOptions{
        Start: time.Now(),
        Parent: parentSpan.TraceContext(),
}
span := tx.StartSpanOptions("SELECT FROM foo", "db.mysql.query", opts)

func StartSpan(ctx context.Context, name, spanType string) (*Span, context.Context)edit

StartSpan starts and returns a new Span within the sampled transaction and parent span in the context, if any. If the span isn’t dropped, it will be indluded in the resulting context.

span, ctx := apm.StartSpan(ctx, "SELECT FROM foo", "db.mysql.query")

func (*Span) End()edit

End marks the span as complete; it must not be used after this.

The span’s duration will be calculated as the amount of time elapsed since the span was started until this call. To override this behaviour, the span’s Duration field may be set before calling End.

func (*Span) Dropped() booledit

Dropped indicates whether or not the span is dropped, meaning it will not be reported to the APM server. Spans are dropped when the created via a nil or non-sampled transaction, or one whose max spans limit has been reached.

func (*Span) TraceContext() TraceContextedit

TraceContext returns the span’s trace context.

func ContextWithSpan(context.Context, *Span) context.Contextedit

ContextWithSpan adds the span to the context, and returns the resulting context.

The span can be retrieved using apm.SpanFromContext. The context may also be passed into apm.StartSpan, which uses SpanFromContext under the covers to create another span as a child of the span.

func SpanFromContext(context.Context) *Spanedit

SpanFromContext returns a span previously stored in the context using apm.ContextWithSpan, or nil if the context does not contain a span.

Contextedit

When reporting transactions and errors you can provide context to describe those events. Built-in instrumentation will typically provide some context, e.g. the URL and remote address for an HTTP request. You can also provide custom context and tags.

func (*Context) SetTag(key, value string)edit

SetTag tags the transaction or error with the given key and value. If the key contains any special characters (., *, "), they will be replaced with underscores. Values longer than 1024 characters will be truncated. Tags will be indexed in Elasticsearch as keyword fields.

func (*Context) SetUsername(username string)edit

SetUsername records the username of the user associated with the transaction.

func (*Context) SetUserID(id string)edit

SetUserID records the ID of the user associated with the transaction.

func (*Context) SetUserEmail(email string)edit

SetUserEmail records the email address of the user associated with the transaction.

Errorsedit

Elastic APM provides two methods of capturing an error event: reporting an error log record, and reporting an "exception" (either a panic or an error in Go parlance).

func (*Tracer) NewError(error) *Erroredit

NewError returns a new Error with details taken from err.

The exception message will be set to err.Error(). The exception module and type will be set to the package and type name of the cause of the error, respectively, where the cause has the same definition as given by github.com/pkg/errors.

e := apm.DefaultTracer.NewError(err)
...
e.Send()

The provided error can implement any of several interfaces to provide additional information:

// Errors implementing ErrorsStacktracer will have their stacktrace
// set based on the result of the StackTrace method.
type ErrorsStacktracer interface {
    StackTrace() github.com/pkg/errors.StackTrace
}

// Errors implementing Stacktracer will have their stacktrace
// set based on the result of the StackTrace method.
type Stacktracer interface {
    StackTrace() []go.elastic.co/apm/stacktrace.Frame
}

// Errors implementing Typer will have a "type" field set to the
// result of the Type method.
type Typer interface {
        Type() string
}

// Errors implementing StringCoder will have a "code" field set to the
// result of the Code method.
type StringCoder interface {
        Code() string
}

// Errors implementing NumberCoder will have a "code" field set to the
// result of the Code method.
type NumberCoder interface {
        Code() float64
}

Errors created by with NewError will have their ID field populated with a unique ID. This can be used in your application for correlation.

func (*Tracer) NewErrorLog(ErrorLogRecord) *Erroredit

NewErrorLog returns a new Error for the given ErrorLogRecord:

type ErrorLogRecord struct {
        // Message holds the message for the log record,
        // e.g. "failed to connect to %s".
        //
        // If this is empty, "[EMPTY]" will be used.
        Message string

        // MessageFormat holds the non-interpolated format
        // of the log record, e.g. "failed to connect to %s".
        //
        // This is optional.
        MessageFormat string

        // Level holds the severity level of the log record.
        //
        // This is optional.
        Level string

        // LoggerName holds the name of the logger used.
        //
        // This is optional.
        LoggerName string
}

The resulting Error’s stacktrace will not be set. Call the SetStacktrace method to set it, if desired.

e := apm.DefaultTracer.NewErrorLog(apm.ErrorLogRecord{
        Message: "Somebody set up us the bomb.",
})
...
e.Send()

func (*Error) SetTransaction(*Transaction)edit

SetTransaction associates the error with the given transaction. The transaction’s End method must not yet have been called.

func (*Error) SetSpan(*Span)edit

SetSpan associates the error with the given span, and the span’s transaction. When calling SetSpan, it is not necessary to also call SetTransaction. The span’s End method must not yet have been called.

func (*Error) Send()edit

Send enqueues the error for sending to the Elastic APM server. The Error must not be used after this.

func (*Tracer) Recovered(interface{}) *Erroredit

Recovered returns an Error from the recovered value, optionally associating it with a transaction. The error is not sent; it is the responsibility of the caller to set the error’s context as desired, and then call its Send method.

tx := apm.DefaultTracer.StartTransaction(...)
defer tx.End()
defer func() {
        if v := recover(); v != nil {
                e := apm.DefaultTracer.Recovered(v)
                e.SetTransaction(tx)
                e.Send()
        }
}()

func CaptureError(context.Context, error) *Erroredit

CaptureError returns a new Error related to the sampled transaction and span present in the context, if any, and sets its exception details using the given error. The Error.Handled field will be set to true, and a stacktrace set.

If there is no transaction in the context, or it is not being sampled, CaptureError returns nil. As a convenience, if the provided error is nil, then CaptureError will also return nil.

if err != nil {
        e := apm.CaptureError(ctx, err)
        e.Send()
}

Trace Contextedit

Trace context contains the ID for a transaction or span, the ID of the end-to-end trace to which the transaction or span belongs, and trace options such as flags relating to sampling. Trace context is propagated between processes, e.g. in HTTP headers, in order to correlate events originating from related services.

Elastic APM’s trace context is based on the W3C Trace Context draft.

Error Contextedit

Errors can be associated with context just like transactions. See Contextedit for details. In addition, errors can be associated with an active transaction or span using SetTransaction or SetSpan, respectively.

tx := apm.DefaultTracer.StartTransaction("GET /foo", "request")
defer tx.End()
e := apm.DefaultTracer.NewError(err)
e.SetTransaction(tx)
e.Send()