Back to godoc.org
go.elastic.co/apm

Package apm

v1.8.0
Latest Go to latest

The latest major version is .

Published: May 6, 2020 | License: Apache-2.0 | Module: go.elastic.co/apm

Overview

Package apm provides an API for tracing transactions and capturing errors, sending the data to Elastic APM.

Index

Examples

Constants

const (
	// AgentVersion is the Elastic APM Go Agent version.
	AgentVersion = "1.8.0"
)

func ContextWithSpan

func ContextWithSpan(parent context.Context, s *Span) context.Context

ContextWithSpan returns a copy of parent in which the given span is stored, associated with the key ContextSpanKey.

func ContextWithTransaction

func ContextWithTransaction(parent context.Context, t *Transaction) context.Context

ContextWithTransaction returns a copy of parent in which the given transaction is stored, associated with the key ContextTransactionKey.

func DetachedContext

func DetachedContext(ctx context.Context) context.Context

DetachedContext returns a new context detached from the lifetime of ctx, but which still returns the values of ctx.

DetachedContext can be used to maintain the trace context required to correlate events, but where the operation is "fire-and-forget", and should not be affected by the deadline or cancellation of ctx.

func RegisterErrorDetailer

func RegisterErrorDetailer(e ErrorDetailer)

RegisterErrorDetailer registers e in the global list of ErrorDetailers.

Each ErrorDetailer registered in this way will be called, in the order registered, for each error created via Tracer.NewError or Tracer.NewErrorLog.

RegisterErrorDetailer must not be called during tracer operation; it is intended to be called at package init time.

func RegisterTypeErrorDetailer

func RegisterTypeErrorDetailer(t reflect.Type, e ErrorDetailer)

RegisterTypeErrorDetailer registers e to be called for any error with the concrete type t.

Each ErrorDetailer registered in this way will be called, in the order registered, for each error of type t created via Tracer.NewError or Tracer.NewErrorLog.

RegisterTypeErrorDetailer must not be called during tracer operation; it is intended to be called at package init time.

func TraceFormatter

func TraceFormatter(ctx context.Context) fmt.Formatter

TraceFormatter returns a fmt.Formatter that can be used to format the identifiers of the transaction and span in ctx.

The returned Formatter understands the following verbs:

%v: trace ID, transaction ID, and span ID (if existing), space-separated
    the plus flag (%+v) adds field names, e.g. "trace.id=... transaction.id=..."
%t: trace ID (hex-encoded, or empty string if non-existent)
    the plus flag (%+T) adds the field name, e.g. "trace.id=..."
%x: transaction ID (hex-encoded, or empty string if non-existent)
    the plus flag (%+t) adds the field name, e.g. "transaction.id=..."
%s: span ID (hex-encoded, or empty string if non-existent)
    the plus flag (%+s) adds the field name, e.g. "span.id=..."
Example

Code:

package main

import (
	"context"
	"go.elastic.co/apm"
	"go.elastic.co/apm/apmtest"
	"log"
)

func main() {
	apmtest.WithTransaction(func(ctx context.Context) {
		span, ctx := apm.StartSpan(ctx, "name", "type")
		defer span.End()

		// The %+v format will add
		//
		//     "trace.id=... transaction.id=... span.id=..."
		//
		// to the log output.
		log.Printf("ERROR [%+v] blah blah", apm.TraceFormatter(ctx))
	})
}

type BodyCapturer

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

BodyCapturer is returned by Tracer.CaptureHTTPRequestBody to later be passed to Context.SetHTTPRequestBody.

Calling Context.SetHTTPRequestBody will reset req.Body to its original value, and invalidates the BodyCapturer.

func (*BodyCapturer) Discard

func (bc *BodyCapturer) Discard()

Discard discards the body capturer: the original request body is replaced, and the body capturer is returned to a pool for reuse. The BodyCapturer must not be used after calling this.

Discard has no effect if bc is nil.

type CaptureBodyMode

type CaptureBodyMode int

CaptureBodyMode holds a value indicating how a tracer should capture HTTP request bodies: for transactions, for errors, for both, or neither.

const (
	// CaptureBodyOff disables capturing of HTTP request bodies. This is
	// the default mode.
	CaptureBodyOff CaptureBodyMode = 0

	// CaptureBodyErrors captures HTTP request bodies for only errors.
	CaptureBodyErrors CaptureBodyMode = 1

	// CaptureBodyTransactions captures HTTP request bodies for only
	// transactions.
	CaptureBodyTransactions CaptureBodyMode = 1 << 1

	// CaptureBodyAll captures HTTP request bodies for both transactions
	// and errors.
	CaptureBodyAll CaptureBodyMode = CaptureBodyErrors | CaptureBodyTransactions
)

type Context

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

Context provides methods for setting transaction and error context.

NOTE this is entirely unrelated to the standard library's context.Context.

func (*Context) SetCustom

func (c *Context) SetCustom(key string, value interface{})

SetCustom sets custom context.

Invalid characters ('.', '*', and '"') in the key will be replaced with an underscore. The value may be any JSON-encodable value.

Example

Code:

package main

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

func main() {
	var ctx context.Context // request context
	tx := apm.TransactionFromContext(ctx)
	tx.Context.SetCustom("key", "value")
}

func (*Context) SetFramework

func (c *Context) SetFramework(name, version string)

SetFramework sets the framework name and version in the context.

This is used for identifying the framework in which the context was created, such as Gin or Echo.

If the name is empty, this is a no-op. If version is empty, then it will be set to "unspecified".

func (*Context) SetHTTPRequest

func (c *Context) SetHTTPRequest(req *http.Request)

SetHTTPRequest sets details of the HTTP request in the context.

This function relates to server-side requests. Various proxy forwarding headers are taken into account to reconstruct the URL, and determining the client address.

If the request URL contains user info, it will be removed and excluded from the URL's "full" field.

If the request contains HTTP Basic Authentication, the username from that will be recorded in the context. Otherwise, if the request contains user info in the URL (i.e. a client-side URL), that will be used.

func (*Context) SetHTTPRequestBody

func (c *Context) SetHTTPRequestBody(bc *BodyCapturer)

SetHTTPRequestBody sets the request body in context given a (possibly nil) BodyCapturer returned by Tracer.CaptureHTTPRequestBody.

func (*Context) SetHTTPResponseHeaders

func (c *Context) SetHTTPResponseHeaders(h http.Header)

SetHTTPResponseHeaders sets the HTTP response headers in the context.

func (*Context) SetHTTPStatusCode

func (c *Context) SetHTTPStatusCode(statusCode int)

SetHTTPStatusCode records the HTTP response status code.

func (*Context) SetLabel

func (c *Context) SetLabel(key string, value interface{})

SetLabel sets a label in the context.

Invalid characters ('.', '*', and '"') in the key will be replaced with underscores.

If the value is numerical or boolean, then it will be sent to the server as a JSON number or boolean; otherwise it will converted to a string, using `fmt.Sprint` if necessary. String values longer than 1024 characters will be truncated.

func (*Context) SetTag

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

SetTag calls SetLabel(key, value).

SetTag is deprecated, and will be removed in a future major version.

func (*Context) SetUserEmail

func (c *Context) SetUserEmail(email string)

SetUserEmail sets the email for the authenticated user.

Example

Code:

package main

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

func main() {
	var ctx context.Context // request context
	tx := apm.TransactionFromContext(ctx)
	tx.Context.SetUsername("admin@example.com")
}

func (*Context) SetUserID

func (c *Context) SetUserID(id string)

SetUserID sets the ID of the authenticated user.

Example

Code:

package main

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

func main() {
	var ctx context.Context // request context
	tx := apm.TransactionFromContext(ctx)
	tx.Context.SetUserID("1000")
}

func (*Context) SetUsername

func (c *Context) SetUsername(username string)

SetUsername sets the username of the authenticated user.

Example

Code:

package main

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

func main() {
	var ctx context.Context // request context
	tx := apm.TransactionFromContext(ctx)
	tx.Context.SetUsername("root")
}

type DatabaseSpanContext

type DatabaseSpanContext struct {
	// Instance holds the database instance name.
	Instance string

	// Statement holds the statement executed in the span,
	// e.g. "SELECT * FROM foo".
	Statement string

	// Type holds the database type, e.g. "sql".
	Type string

	// User holds the username used for database access.
	User string
}

DatabaseSpanContext holds database span context.

type DestinationServiceSpanContext

type DestinationServiceSpanContext struct {
	// Name holds a name for the destination service, which may be used
	// for grouping and labeling in service maps.
	Name string

	// Resource holds an identifier for a destination service resource,
	// such as a message queue.
	Resource string
}

DestinationServiceSpanContext holds destination service span span.

type Error

type Error struct {
	// ErrorData holds the error data. This field is set to nil when
	// the error's Send method is called.
	*ErrorData
	// contains filtered or unexported fields
}

Error describes an error occurring in the monitored service.

func CaptureError

func CaptureError(ctx context.Context, err error) *Error

CaptureError returns a new Error related to the sampled transaction and span present in the context, if any, and sets its exception info from err. The Error.Handled field will be set to true, and a stacktrace set either from err, or from the caller.

If the provided error is nil, then CaptureError will also return nil; otherwise a non-nil Error will always be returned. If there is no transaction or span in the context, then the returned Error's Send method will have no effect.

func (*Error) Cause

func (e *Error) Cause() error

Cause returns original error assigned to Error, nil if Error or Error.cause is nil. https://godoc.org/github.com/pkg/errors#Cause

func (*Error) Error

func (e *Error) Error() string

Error returns string message for error. if Error or Error.cause is nil, "[EMPTY]" will be used.

func (*Error) Send

func (e *Error) Send()

Send enqueues the error for sending to the Elastic APM server.

Send will set e.ErrorData to nil, so the error must not be modified after Send returns.

func (*Error) SetSpan

func (e *Error) SetSpan(s *Span)

SetSpan sets TraceID, TransactionID, and ParentID to the span's IDs.

There is no need to call both SetTransaction and SetSpan. If you do call both, then SetSpan must be called second in order to set the error's ParentID correctly.

If any custom context has been recorded in s's transaction, it will also be carried across to e, but will not override any custom context already recorded on e.

func (*Error) SetStacktrace

func (e *Error) SetStacktrace(skip int)

SetStacktrace sets the stacktrace for the error, skipping the first skip number of frames, excluding the SetStacktrace function.

func (*Error) SetTransaction

func (e *Error) SetTransaction(tx *Transaction)

SetTransaction sets TraceID, TransactionID, and ParentID to the transaction's IDs, and records the transaction's Type and whether or not it was sampled.

If any custom context has been recorded in tx, it will also be carried across to e, but will not override any custom context already recorded on e.

type ErrorData

type ErrorData struct {

	// ID is the unique identifier of the error. This is set by
	// the various error constructors, and is exposed only so
	// the error ID can be logged or displayed to the user.
	ID ErrorID

	// TraceID is the unique identifier of the trace in which
	// this error occurred. If the error is not associated with
	// a trace, this will be the zero value.
	TraceID TraceID

	// TransactionID is the unique identifier of the transaction
	// in which this error occurred. If the error is not associated
	// with a transaction, this will be the zero value.
	TransactionID SpanID

	// ParentID is the unique identifier of the transaction or span
	// in which this error occurred. If the error is not associated
	// with a transaction or span, this will be the zero value.
	ParentID SpanID

	// Culprit is the name of the function that caused the error.
	//
	// This is initially unset; if it remains unset by the time
	// Send is invoked, and the error has a stacktrace, the first
	// non-library frame in the stacktrace will be considered the
	// culprit.
	Culprit string

	// Timestamp records the time at which the error occurred.
	// This is set when the Error object is created, but may
	// be overridden any time before the Send method is called.
	Timestamp time.Time

	// Handled records whether or not the error was handled. This
	// is ignored by "log" errors with no associated error value.
	Handled bool

	// Context holds the context for this error.
	Context Context
	// contains filtered or unexported fields
}

ErrorData holds the details for an error, and is embedded inside Error. When the error is sent, its ErrorData field will be set to nil.

type ErrorDetailer

type ErrorDetailer interface {
	// ErrorDetails is called to update or alter details for err.
	ErrorDetails(err error, details *ErrorDetails)
}

ErrorDetailer defines an interface for altering or extending the ErrorDetails for an error.

ErrorDetailers can be registered using the package-level functions RegisterErrorDetailer and RegisterTypeErrorDetailer.

type ErrorDetailerFunc

type ErrorDetailerFunc func(error, *ErrorDetails)

ErrorDetailerFunc is a function type implementing ErrorDetailer.

func (ErrorDetailerFunc) ErrorDetails

func (f ErrorDetailerFunc) ErrorDetails(err error, details *ErrorDetails)

ErrorDetails calls f(err, details).

type ErrorDetails

type ErrorDetails struct {

	// Type holds information about the error type, initialized
	// with the type name and type package path using reflection.
	Type struct {
		// Name holds the error type name.
		Name string

		// PackagePath holds the error type package path.
		PackagePath string
	}

	// Code holds an error code.
	Code struct {
		// String holds a string-based error code. If this is set, then Number is ignored.
		//
		// This field will be initialized to the result of calling an error's Code method,
		// if the error implements the following interface:
		//
		//     type interface StringCoder {
		//         Code() string
		//     }
		String string

		// Number holds a numerical error code. This is ignored if String is set.
		//
		// This field will be initialized to the result of calling an error's Code
		// method, if the error implements the following interface:
		//
		//     type interface NumberCoder {
		//         Code() float64
		//     }
		Number float64
	}

	// Cause holds the errors that were the cause of this error.
	Cause []error
	// contains filtered or unexported fields
}

ErrorDetails holds details of an error, which can be altered or extended by registering an ErrorDetailer with RegisterErrorDetailer or RegisterTypeErrorDetailer.

func (*ErrorDetails) SetAttr

func (d *ErrorDetails) SetAttr(k string, v interface{})

SetAttr sets the attribute with key k to value v.

type ErrorID

type ErrorID TraceID

ErrorID uniquely identifies an error.

func (ErrorID) String

func (id ErrorID) String() string

String returns id in its hex-encoded format.

type 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

	// Error is an error associated with the log record.
	//
	// This is optional.
	Error error
}

ErrorLogRecord holds details of an error log record.

type GatherMetricsFunc

type GatherMetricsFunc func(context.Context, *Metrics) error

GatherMetricsFunc is a function type implementing MetricsGatherer.

func (GatherMetricsFunc) GatherMetrics

func (f GatherMetricsFunc) GatherMetrics(ctx context.Context, m *Metrics) error

GatherMetrics calls f(ctx, m).

type Logger

type Logger interface {
	// Debugf logs a message at debug level.
	Debugf(format string, args ...interface{})

	// Errorf logs a message at error level.
	Errorf(format string, args ...interface{})
}

Logger is an interface for logging, used by the tracer to log tracer errors and other interesting events.

type MetricLabel

type MetricLabel struct {
	// Name is the label name.
	Name string

	// Value is the label value.
	Value string
}

MetricLabel is a name/value pair for labeling metrics.

type Metrics

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

Metrics holds a set of metrics.

func (*Metrics) Add

func (m *Metrics) Add(name string, labels []MetricLabel, value float64)

Add adds a metric with the given name, labels, and value, The labels are expected to be sorted lexicographically.

type MetricsGatherer

type MetricsGatherer interface {
	// GatherMetrics gathers metrics and adds them to m.
	//
	// If ctx.Done() is signaled, gathering should be aborted and
	// ctx.Err() returned. If GatherMetrics returns an error, it
	// will be logged, but otherwise there is no effect; the
	// implementation must take care not to leave m in an invalid
	// state due to errors.
	GatherMetrics(ctx context.Context, m *Metrics) error
}

MetricsGatherer provides an interface for gathering metrics.

type Sampler

type Sampler interface {
	// Sample indicates whether or not a transaction
	// should be sampled. This method will be invoked
	// by calls to Tracer.StartTransaction for the root
	// of a trace, so it must be goroutine-safe, and
	// should avoid synchronization as far as possible.
	Sample(TraceContext) bool
}

Sampler provides a means of sampling transactions.

func NewRatioSampler

func NewRatioSampler(r float64) Sampler

NewRatioSampler returns a new Sampler with the given ratio

A ratio of 1.0 samples 100% of transactions, a ratio of 0.5 samples ~50%, and so on. If the ratio provided does not lie within the range [0,1.0], NewRatioSampler will panic.

The returned Sampler bases its decision on the value of the transaction ID, so there is no synchronization involved.

type Span

type Span struct {

	// SpanData holds the span data. This field is set to nil when
	// the span's End method is called.
	*SpanData
	// contains filtered or unexported fields
}

Span describes an operation within a transaction.

func SpanFromContext

func SpanFromContext(ctx context.Context) *Span

SpanFromContext returns the current Span in context, if any. The span must have been added to the context previously using ContextWithSpan, or the top-level StartSpan function.

func StartSpan

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

StartSpan is equivalent to calling StartSpanOptions with a zero SpanOptions struct.

func StartSpanOptions

func StartSpanOptions(ctx context.Context, name, spanType string, opts SpanOptions) (*Span, context.Context)

StartSpanOptions 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 stored in the resulting context.

If opts.Parent is non-zero, its value will be used in preference to any parent span in ctx.

StartSpanOptions always returns a non-nil Span. Its End method must be called when the span completes.

func (*Span) Dropped

func (s *Span) Dropped() bool

Dropped indicates whether or not the span is dropped, meaning it will not be included in any transaction. Spans are dropped by Transaction.StartSpan if the transaction is nil, non-sampled, or the transaction's max spans limit has been reached.

Dropped may be used to avoid any expensive computation required to set the span's context.

func (*Span) End

func (s *Span) End()

End marks the s as being complete; s must not be used after this.

If s.Duration has not been set, End will set it to the elapsed time since the span's start time.

func (*Span) SetStacktrace

func (s *Span) SetStacktrace(skip int)

SetStacktrace sets the stacktrace for the span, skipping the first skip number of frames, excluding the SetStacktrace function.

func (*Span) TraceContext

func (s *Span) TraceContext() TraceContext

TraceContext returns the span's TraceContext.

type SpanContext

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

SpanContext provides methods for setting span context.

func (*SpanContext) SetDatabase

func (c *SpanContext) SetDatabase(db DatabaseSpanContext)

SetDatabase sets the span context for database-related operations.

func (*SpanContext) SetDatabaseRowsAffected

func (c *SpanContext) SetDatabaseRowsAffected(n int64)

SetDatabaseRowsAffected records the number of rows affected by a database operation.

func (*SpanContext) SetDestinationAddress

func (c *SpanContext) SetDestinationAddress(addr string, port int)

SetDestinationAddress sets the destination address and port in the context.

SetDestinationAddress has no effect when called when an empty addr.

func (*SpanContext) SetDestinationService

func (c *SpanContext) SetDestinationService(service DestinationServiceSpanContext)

SetDestinationService sets the destination service info in the context.

func (*SpanContext) SetHTTPRequest

func (c *SpanContext) SetHTTPRequest(req *http.Request)

SetHTTPRequest sets the details of the HTTP request in the context.

This function relates to client requests. If the request URL contains user info, it will be removed and excluded from the stored URL.

SetHTTPRequest makes implicit calls to SetDestinationAddress and SetDestinationService, using details from req.URL.

func (*SpanContext) SetHTTPStatusCode

func (c *SpanContext) SetHTTPStatusCode(statusCode int)

SetHTTPStatusCode records the HTTP response status code.

func (*SpanContext) SetLabel

func (c *SpanContext) SetLabel(key string, value interface{})

SetLabel sets a label in the context.

Invalid characters ('.', '*', and '"') in the key will be replaced with underscores.

If the value is numerical or boolean, then it will be sent to the server as a JSON number or boolean; otherwise it will converted to a string, using `fmt.Sprint` if necessary. String values longer than 1024 characters will be truncated.

func (*SpanContext) SetTag

func (c *SpanContext) SetTag(key, value string)

SetTag calls SetLabel(key, value).

SetTag is deprecated, and will be removed in a future major version.

type SpanData

type SpanData struct {

	// Name holds the span name, initialized with the value passed to StartSpan.
	Name string

	// Type holds the overarching span type, such as "db", and will be initialized
	// with the value passed to StartSpan.
	Type string

	// Subtype holds the span subtype, such as "mysql". This will initially be empty,
	// and can be set after starting the span.
	Subtype string

	// Action holds the span action, such as "query". This will initially be empty,
	// and can be set after starting the span.
	Action string

	// Duration holds the span duration, initialized to -1.
	//
	// If you do not update Duration, calling Span.End will calculate the
	// duration based on the elapsed time since the span's start time.
	Duration time.Duration

	// Context describes the context in which span occurs.
	Context SpanContext
	// contains filtered or unexported fields
}

SpanData holds the details for a span, and is embedded inside Span. When a span is ended or discarded, its SpanData field will be set to nil.

type SpanID

type SpanID [8]byte

SpanID identifies a span within a trace.

func (SpanID) MarshalText

func (id SpanID) MarshalText() ([]byte, error)

MarshalText returns id encoded as hex, satisfying encoding.TextMarshaler.

func (SpanID) String

func (id SpanID) String() string

String returns id encoded as hex.

func (SpanID) Validate

func (id SpanID) Validate() error

Validate validates the span ID. This will return non-nil for a zero span ID.

type SpanOptions

type SpanOptions struct {
	// Parent, if non-zero, holds the trace context of the parent span.
	Parent TraceContext

	// SpanID holds the ID to assign to the span. If this is zero, a new ID
	// will be generated and used instead.
	SpanID SpanID

	// Start is the start time of the span. If this has the zero value,
	// time.Now() will be used instead.
	//
	// When a span is created using Transaction.StartSpanOptions, the
	// span timestamp is internally calculated relative to the transaction
	// timestamp.
	//
	// When Tracer.StartSpan is used, this timestamp should be pre-calculated
	// as relative from the transaction start time, i.e. by calculating the
	// time elapsed since the transaction started, and adding that to the
	// transaction timestamp. Calculating the timstamp in this way will ensure
	// monotonicity of events within a transaction.
	Start time.Time
	// contains filtered or unexported fields
}

SpanOptions holds options for Transaction.StartSpanOptions and Tracer.StartSpan.

type TraceContext

type TraceContext struct {
	// Trace identifies the trace forest.
	Trace TraceID

	// Span identifies a span: the parent span if this context
	// corresponds to an incoming request, or the current span
	// if this is an outgoing request.
	Span SpanID

	// Options holds the trace options propagated by the parent.
	Options TraceOptions

	// State holds the trace state.
	State TraceState
}

TraceContext holds trace context for an incoming or outgoing request.

type TraceID

type TraceID [16]byte

TraceID identifies a trace forest.

func (TraceID) MarshalText

func (id TraceID) MarshalText() ([]byte, error)

MarshalText returns id encoded as hex, satisfying encoding.TextMarshaler.

func (TraceID) String

func (id TraceID) String() string

String returns id encoded as hex.

func (TraceID) Validate

func (id TraceID) Validate() error

Validate validates the trace ID. This will return non-nil for a zero trace ID.

type TraceOptions

type TraceOptions uint8

TraceOptions describes the options for a trace.

func (TraceOptions) Recorded

func (o TraceOptions) Recorded() bool

Recorded reports whether or not the transaction/span may have been (or may be) recorded.

func (TraceOptions) WithRecorded

func (o TraceOptions) WithRecorded(recorded bool) TraceOptions

WithRecorded changes the "recorded" flag, and returns the new options without modifying the original value.

type TraceState

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

TraceState holds vendor-specific state for a trace.

func NewTraceState

func NewTraceState(entries ...TraceStateEntry) TraceState

NewTraceState returns a TraceState based on entries.

func (TraceState) String

func (s TraceState) String() string

String returns s as a comma-separated list of key-value pairs.

func (TraceState) Validate

func (s TraceState) Validate() error

Validate validates the trace state.

This will return non-nil if any entries are invalid, if there are too many entries, or if an entry key is repeated.

type TraceStateEntry

type TraceStateEntry struct {

	// Key holds a vendor (and optionally, tenant) ID.
	Key string

	// Value holds a string representing trace state.
	Value string
	// contains filtered or unexported fields
}

TraceStateEntry holds a trace state entry: a key/value pair representing state for a vendor.

func (*TraceStateEntry) Validate

func (e *TraceStateEntry) Validate() error

Validate validates the trace state entry.

This will return non-nil if either the key or value is invalid.

type Tracer

type Tracer struct {
	Transport transport.Transport
	Service   struct {
		Name        string
		Version     string
		Environment string
	}
	// contains filtered or unexported fields
}

Tracer manages the sampling and sending of transactions to Elastic APM.

Transactions are buffered until they are flushed (forcibly with a Flush call, or when the flush timer expires), or when the maximum transaction queue size is reached. Failure to send will be periodically retried. Once the queue limit has been reached, new transactions will replace older ones in the queue.

Errors are sent as soon as possible, but will buffered and later sent in bulk if the tracer is busy, or otherwise cannot send to the server, e.g. due to network failure. There is a limit to the number of errors that will be buffered, and once that limit has been reached, new errors will be dropped until the queue is drained.

The exported fields be altered or replaced any time up until any Tracer methods have been invoked.

Example

ExampleTracer shows how to use the Tracer API

Code:

// Licensed to Elasticsearch B.V. under one or more contributor
// license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright
// ownership. Elasticsearch B.V. licenses this file to you under
// the Apache License, Version 2.0 (the "License"); you may
// not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

package main

import (
	"compress/zlib"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"os"
	"sync"
	"time"

	"go.elastic.co/apm"
	"go.elastic.co/apm/transport"
)

// ExampleTracer shows how to use the Tracer API
func main() {
	var r recorder
	server := httptest.NewServer(&r)
	defer server.Close()

	// ELASTIC_APM_SERVER_URL should typically set in the environment
	// when the process is started. The InitDefault call below is only
	// required in this case because the environment variable is set
	// after the program has been initialized.
	os.Setenv("ELASTIC_APM_SERVER_URL", server.URL)
	defer os.Unsetenv("ELASTIC_APM_SERVER_URL")
	transport.InitDefault()

	const serviceName = "service-name"
	const serviceVersion = "1.0.0"
	tracer, err := apm.NewTracer(serviceName, serviceVersion)
	if err != nil {
		log.Fatal(err)
	}
	defer tracer.Close()

	// api is a very basic API handler, to demonstrate the usage
	// of the tracer. api.handlerOrder creates a transaction for
	// every call; api.handleOrder calls through to storeOrder,
	// which adds a span to the transaction.
	api := &api{tracer: tracer}
	api.handleOrder(context.Background(), "fish fingers")
	api.handleOrder(context.Background(), "detergent")

	// The tracer will stream events to the APM server, and will
	// close the request when it reaches a given size in bytes
	// (ELASTIC_APM_API_REQUEST_SIZE) or a given duration has
	// elapsed (ELASTIC_APM_API_REQUEST_TIME). Even so, we flush
	// here to ensure the data reaches the server.
	tracer.Flush(nil)

	fmt.Println("number of payloads:", len(r.payloads))
	metadata := r.payloads[0]["metadata"].(map[string]interface{})
	service := metadata["service"].(map[string]interface{})
	agent := service["agent"].(map[string]interface{})
	language := service["language"].(map[string]interface{})
	runtime := service["runtime"].(map[string]interface{})
	fmt.Println("  service name:", service["name"])
	fmt.Println("  service version:", service["version"])
	fmt.Println("  agent name:", agent["name"])
	fmt.Println("  language name:", language["name"])
	fmt.Println("  runtime name:", runtime["name"])

	var transactions []map[string]interface{}
	var spans []map[string]interface{}
	for _, p := range r.payloads[1:] {
		t, ok := p["transaction"].(map[string]interface{})
		if ok {
			transactions = append(transactions, t)
			continue
		}
		s, ok := p["span"].(map[string]interface{})
		if ok {
			spans = append(spans, s)
			continue
		}
	}
	if len(transactions) != len(spans) {
		fmt.Printf("%d transaction(s), %d span(s)\n", len(transactions), len(spans))
		return
	}
	for i, t := range transactions {
		s := spans[i]
		fmt.Printf("  transaction %d:\n", i)
		fmt.Println("    name:", t["name"])
		fmt.Println("    type:", t["type"])
		fmt.Println("    context:", t["context"])
		fmt.Printf("    span %d:\n", i)
		fmt.Println("      name:", s["name"])
		fmt.Println("      type:", s["type"])
	}

}

type api struct {
	tracer *apm.Tracer
}

func (api *api) handleOrder(ctx context.Context, product string) {
	tx := api.tracer.StartTransaction("order", "request")
	defer tx.End()
	ctx = apm.ContextWithTransaction(ctx, tx)

	tx.Context.SetLabel("product", product)

	time.Sleep(10 * time.Millisecond)
	storeOrder(ctx, product)
	time.Sleep(20 * time.Millisecond)
}

func storeOrder(ctx context.Context, product string) {
	span, _ := apm.StartSpan(ctx, "store_order", "rpc")
	defer span.End()

	time.Sleep(50 * time.Millisecond)
}

type recorder struct {
	mu       sync.Mutex
	payloads []map[string]interface{}
}

func (r *recorder) count() int {
	r.mu.Lock()
	defer r.mu.Unlock()
	return len(r.payloads)
}

func (r *recorder) ServeHTTP(w http.ResponseWriter, req *http.Request) {
	if req.URL.Path != "/intake/v2/events" {
		// Ignore config requests.
		return
	}
	body, err := zlib.NewReader(req.Body)
	if err != nil {
		panic(err)
	}
	decoder := json.NewDecoder(body)
	var payloads []map[string]interface{}
	for {
		var m map[string]interface{}
		if err := decoder.Decode(&m); err != nil {
			if err == io.EOF {
				break
			}
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
		payloads = append(payloads, m)
	}
	r.mu.Lock()
	r.payloads = append(r.payloads, payloads...)
	r.mu.Unlock()
}
number of payloads: 5
  service name: service-name
  service version: 1.0.0
  agent name: go
  language name: go
  runtime name: gc
  transaction 0:
    name: order
    type: request
    context: map[tags:map[product:fish fingers]]
    span 0:
      name: store_order
      type: rpc
  transaction 1:
    name: order
    type: request
    context: map[tags:map[product:detergent]]
    span 1:
      name: store_order
      type: rpc
var (
	// DefaultTracer is the default global Tracer, set at package
	// initialization time, configured via environment variables.
	//
	// This will always be initialized to a non-nil value. If any
	// of the environment variables are invalid, the corresponding
	// errors will be logged to stderr and the default values will
	// be used instead.
	DefaultTracer *Tracer
)

func NewTracer

func NewTracer(serviceName, serviceVersion string) (*Tracer, error)

NewTracer returns a new Tracer, using the default transport, and with the specified service name and version if specified. This is equivalent to calling NewTracerOptions with a TracerOptions having ServiceName and ServiceVersion set to the provided arguments.

func NewTracerOptions

func NewTracerOptions(opts TracerOptions) (*Tracer, error)

NewTracerOptions returns a new Tracer using the provided options. See TracerOptions for details on the options, and their default values.

func (*Tracer) Active

func (t *Tracer) Active() bool

Active reports whether the tracer is active. If the tracer is inactive, no transactions or errors will be sent to the Elastic APM server.

func (*Tracer) CaptureHTTPRequestBody

func (t *Tracer) CaptureHTTPRequestBody(req *http.Request) *BodyCapturer

CaptureHTTPRequestBody replaces req.Body and returns a possibly nil BodyCapturer which can later be passed to Context.SetHTTPRequestBody for setting the request body in a transaction or error context. If the tracer is not configured to capture HTTP request bodies, then req.Body is left alone and nil is returned.

This must be called before the request body is read. The BodyCapturer's Discard method should be called after it is no longer needed, in order to recycle its memory.

func (*Tracer) Close

func (t *Tracer) Close()

Close closes the Tracer, preventing transactions from being sent to the APM server.

func (*Tracer) Flush

func (t *Tracer) Flush(abort <-chan struct{})

Flush waits for the Tracer to flush any transactions and errors it currently has queued to the APM server, the tracer is stopped, or the abort channel is signaled.

func (*Tracer) NewError

func (t *Tracer) NewError(err error) *Error

NewError returns a new Error with details taken from err. NewError will panic if called with a nil error.

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.

If err implements

type interface {
    StackTrace() github.com/pkg/errors.StackTrace
}

or

type interface {
    StackTrace() []stacktrace.Frame
}

then one of those will be used to set the error stacktrace. Otherwise, NewError will take a stacktrace.

If err implements

type interface {Type() string}

then that will be used to set the error type.

If err implements

type interface {Code() string}

or

type interface {Code() float64}

then one of those will be used to set the error code.

func (*Tracer) NewErrorLog

func (t *Tracer) NewErrorLog(r ErrorLogRecord) *Error

NewErrorLog returns a new Error for the given ErrorLogRecord.

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

If r.Message is empty, "[EMPTY]" will be used.

func (*Tracer) Recording

func (t *Tracer) Recording() bool

Recording reports whether the tracer is recording events. Instrumentation may use this to avoid creating transactions, spans, and metrics when the tracer is configured to not record.

Recording will also return false if the tracer is inactive.

func (*Tracer) Recovered

func (t *Tracer) Recovered(v interface{}) *Error

Recovered creates an Error with t.NewError(err), where err is either v (if v implements error), or otherwise fmt.Errorf("%v", v). The value v is expected to have come from a panic.

func (*Tracer) RegisterMetricsGatherer

func (t *Tracer) RegisterMetricsGatherer(g MetricsGatherer) func()

RegisterMetricsGatherer registers g for periodic (or forced) metrics gathering by t.

RegisterMetricsGatherer returns a function which will deregister g. It may safely be called multiple times.

func (*Tracer) SendMetrics

func (t *Tracer) SendMetrics(abort <-chan struct{})

SendMetrics forces the tracer to gather and send metrics immediately, blocking until the metrics have been sent or the abort channel is signalled.

func (*Tracer) SetCaptureBody

func (t *Tracer) SetCaptureBody(mode CaptureBodyMode)

SetCaptureBody sets the HTTP request body capture mode.

func (*Tracer) SetCaptureHeaders

func (t *Tracer) SetCaptureHeaders(capture bool)

SetCaptureHeaders enables or disables capturing of HTTP headers.

func (*Tracer) SetConfigWatcher

func (t *Tracer) SetConfigWatcher(w apmconfig.Watcher)

SetConfigWatcher sets w as the config watcher.

By default, the tracer will be configured to use the transport for watching config, if the transport implements apmconfig.Watcher. This can be overridden by calling SetConfigWatcher.

If w is nil, config watching will be stopped.

Calling SetConfigWatcher will discard any previously observed remote config, reverting to local config until a config change from w is observed.

func (*Tracer) SetContextSetter

func (t *Tracer) SetContextSetter(setter stacktrace.ContextSetter)

SetContextSetter sets the stacktrace.ContextSetter to be used for setting stacktrace source context. If nil (which is the initial value), no context will be set.

func (*Tracer) SetLogger

func (t *Tracer) SetLogger(logger Logger)

SetLogger sets the Logger to be used for logging the operation of the tracer.

If logger implements WarningLogger, its Warningf method will be used for logging warnings. Otherwise, warnings will logged using Debugf.

The tracer is initialized with a default logger configured with the environment variables ELASTIC_APM_LOG_FILE and ELASTIC_APM_LOG_LEVEL. Calling SetLogger will replace the default logger.

func (*Tracer) SetMaxSpans

func (t *Tracer) SetMaxSpans(n int)

SetMaxSpans sets the maximum number of spans that will be added to a transaction before dropping spans.

Passing in zero will disable all spans, while negative values will permit an unlimited number of spans.

func (*Tracer) SetMetricsInterval

func (t *Tracer) SetMetricsInterval(d time.Duration)

SetMetricsInterval sets the metrics interval -- the amount of time in between metrics samples being gathered.

func (*Tracer) SetRecording

func (t *Tracer) SetRecording(r bool)

SetRecording enables or disables recording of future events.

SetRecording does not affect in-flight events.

func (*Tracer) SetRequestDuration

func (t *Tracer) SetRequestDuration(d time.Duration)

SetRequestDuration sets the maximum amount of time to keep a request open to the APM server for streaming data before closing the stream and starting a new request.

func (*Tracer) SetSampler

func (t *Tracer) SetSampler(s Sampler)

SetSampler sets the sampler the tracer.

It is valid to pass nil, in which case all transactions will be sampled.

Configuration via Kibana takes precedence over local configuration, so if sampling has been configured via Kibana, this call will not have any effect until/unless that configuration has been removed.

func (*Tracer) SetSanitizedFieldNames

func (t *Tracer) SetSanitizedFieldNames(patterns ...string) error

SetSanitizedFieldNames sets the wildcard patterns that will be used to match cookie and form field names for sanitization. Fields matching any of the the supplied patterns will have their values redacted. If SetSanitizedFieldNames is called with no arguments, then no fields will be redacted.

func (*Tracer) SetSpanFramesMinDuration

func (t *Tracer) SetSpanFramesMinDuration(d time.Duration)

SetSpanFramesMinDuration sets the minimum duration for a span after which we will capture its stack frames.

func (*Tracer) SetStackTraceLimit

func (t *Tracer) SetStackTraceLimit(limit int)

SetStackTraceLimit sets the the maximum number of stack frames to collect for each stack trace. If limit is negative, then all frames will be collected.

func (*Tracer) ShouldPropagateLegacyHeader

func (t *Tracer) ShouldPropagateLegacyHeader() bool

ShouldPropagateLegacyHeader reports whether instrumentation should propagate the legacy "Elastic-Apm-Traceparent" header in addition to the standard W3C "traceparent" header.

This method will be removed in a future major version when we remove support for propagating the legacy header.

func (*Tracer) StartSpan

func (t *Tracer) StartSpan(name, spanType string, transactionID SpanID, opts SpanOptions) *Span

StartSpan returns a new Span with the specified name, type, transaction ID, and options. The parent transaction context and transaction IDs must have valid, non-zero values, or else the span will be dropped.

In most cases, you should use Transaction.StartSpan or Transaction.StartSpanOptions. This method is provided for corner-cases, such as starting a span after the containing transaction's End method has been called. Spans created in this way will not have the "max spans" configuration applied, nor will they be considered in any transaction's span count.

func (*Tracer) StartTransaction

func (t *Tracer) StartTransaction(name, transactionType string) *Transaction

StartTransaction returns a new Transaction with the specified name and type, and with the start time set to the current time. This is equivalent to calling StartTransactionOptions with a zero TransactionOptions.

func (*Tracer) StartTransactionOptions

func (t *Tracer) StartTransactionOptions(name, transactionType string, opts TransactionOptions) *Transaction

StartTransactionOptions returns a new Transaction with the specified name, type, and options.

func (*Tracer) Stats

func (t *Tracer) Stats() TracerStats

Stats returns the current TracerStats. This will return the most recent values even after the tracer has been closed.

type TracerOptions

type TracerOptions struct {
	// ServiceName holds the service name.
	//
	// If ServiceName is empty, the service name will be defined using the
	// ELASTIC_APM_SERVICE_NAME environment variable, or if that is not set,
	// the executable name.
	ServiceName string

	// ServiceVersion holds the service version.
	//
	// If ServiceVersion is empty, the service version will be defined using
	// the ELASTIC_APM_SERVICE_VERSION environment variable.
	ServiceVersion string

	// ServiceEnvironment holds the service environment.
	//
	// If ServiceEnvironment is empty, the service environment will be defined
	// using the ELASTIC_APM_ENVIRONMENT environment variable.
	ServiceEnvironment string

	// Transport holds the transport to use for sending events.
	//
	// If Transport is nil, transport.Default will be used.
	//
	// If Transport implements apmconfig.Watcher, the tracer will begin watching
	// for remote changes immediately. This behaviour can be disabled by setting
	// the environment variable ELASTIC_APM_CENTRAL_CONFIG=false.
	Transport transport.Transport
	// contains filtered or unexported fields
}

TracerOptions holds initial tracer options, for passing to NewTracerOptions.

type TracerStats

type TracerStats struct {
	Errors              TracerStatsErrors
	ErrorsSent          uint64
	ErrorsDropped       uint64
	TransactionsSent    uint64
	TransactionsDropped uint64
	SpansSent           uint64
	SpansDropped        uint64
}

TracerStats holds statistics for a Tracer.

type TracerStatsErrors

type TracerStatsErrors struct {
	SetContext uint64
	SendStream uint64
}

TracerStatsErrors holds error statistics for a Tracer.

type Transaction

type Transaction struct {

	// TransactionData holds the transaction data. This field is set to
	// nil when either of the transaction's End or Discard methods are called.
	*TransactionData
	// contains filtered or unexported fields
}

Transaction describes an event occurring in the monitored service.

func TransactionFromContext

func TransactionFromContext(ctx context.Context) *Transaction

TransactionFromContext returns the current Transaction in context, if any. The transaction must have been added to the context previously using ContextWithTransaction.

func (*Transaction) Discard

func (tx *Transaction) Discard()

Discard discards a previously started transaction.

Calling Discard will set tx's TransactionData field to nil, so callers must ensure tx is not updated after Discard returns.

func (*Transaction) End

func (tx *Transaction) End()

End enqueues tx for sending to the Elastic APM server.

Calling End will set tx's TransactionData field to nil, so callers must ensure tx is not updated after End returns.

If tx.Duration has not been set, End will set it to the elapsed time since the transaction's start time.

func (*Transaction) EnsureParent

func (tx *Transaction) EnsureParent() SpanID

EnsureParent returns the span ID for for tx's parent, generating a parent span ID if one has not already been set and tx has not been ended. If tx is nil or has been ended, a zero (invalid) SpanID is returned.

This method can be used for generating a span ID for the RUM (Real User Monitoring) agent, where the RUM agent is initialized after the backend service returns.

Example

Code:

package main

import (
	"go.elastic.co/apm"
	"html/template"
	"os"
)

func main() {
	tx := apm.DefaultTracer.StartTransactionOptions("name", "type", apm.TransactionOptions{
		TraceContext: apm.TraceContext{
			Trace: apm.TraceID{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15},
			Span:  apm.SpanID{0, 1, 2, 3, 4, 5, 6, 7},
		},
	})
	defer tx.Discard()

	tpl := template.Must(template.New("").Parse(`
<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>
`))

	if err := tpl.Execute(os.Stdout, tx); err != nil {
		panic(err)
	}

}
<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: "000102030405060708090a0b0c0d0e0f",
    pageLoadSpanId: "0001020304050607",
    pageLoadSampled:  false ,
  })
</script>
Example (NilTransaction)

Code:

package main

import (
	"context"
	"go.elastic.co/apm"
	"html/template"
	"os"
)

func main() {
	tpl := template.Must(template.New("").Parse(`
<script>
elasticApm.init({
  {{.TraceContext.Trace}},
  {{.EnsureParent}},
  {{.Sampled}},
})
</script>
`))

	// Demonstrate that Transaction's TraceContext, EnsureParent,
	// and Sampled methods will not panic when called with a nil
	// Transaction.
	tx := apm.TransactionFromContext(context.Background())
	if err := tpl.Execute(os.Stdout, tx); err != nil {
		panic(err)
	}

}
<script>
elasticApm.init({
  "00000000000000000000000000000000",
  "0000000000000000",
   false ,
})
</script>

func (*Transaction) Sampled

func (tx *Transaction) Sampled() bool

Sampled reports whether or not the transaction is sampled.

func (*Transaction) ShouldPropagateLegacyHeader

func (tx *Transaction) ShouldPropagateLegacyHeader() bool

ShouldPropagateLegacyHeader reports whether instrumentation should propagate the legacy "Elastic-Apm-Traceparent" header in addition to the standard W3C "traceparent" header.

This method will be removed in a future major version when we remove support for propagating the legacy header.

func (*Transaction) StartSpan

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

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.

StartSpan always returns a non-nil Span, with a non-nil SpanData field. Its End method must be called when the span completes.

If the span type contains two dots, they are assumed to separate the span type, subtype, and action; a single dot separates span type and subtype, and the action will not be set.

StartSpan is equivalent to calling StartSpanOptions with SpanOptions.Parent set to the trace context of parent if parent is non-nil.

func (*Transaction) StartSpanOptions

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

StartSpanOptions starts and returns a new Span within the transaction, with the specified name, type, and options.

StartSpan always returns a non-nil Span. Its End method must be called when the span completes.

If the span type contains two dots, they are assumed to separate the span type, subtype, and action; a single dot separates span type and subtype, and the action will not be set.

func (*Transaction) TraceContext

func (tx *Transaction) TraceContext() TraceContext

TraceContext returns the transaction's TraceContext.

The resulting TraceContext's Span field holds the transaction's ID. If tx is nil, a zero (invalid) TraceContext is returned.

type TransactionData

type TransactionData struct {
	// Name holds the transaction name, initialized with the value
	// passed to StartTransaction.
	Name string

	// Type holds the transaction type, initialized with the value
	// passed to StartTransaction.
	Type string

	// Duration holds the transaction duration, initialized to -1.
	//
	// If you do not update Duration, calling Transaction.End will
	// calculate the duration based on the elapsed time since the
	// transaction's start time.
	Duration time.Duration

	// Context describes the context in which the transaction occurs.
	Context Context

	// Result holds the transaction result.
	Result string
	// contains filtered or unexported fields
}

TransactionData holds the details for a transaction, and is embedded inside Transaction. When a transaction is ended, its TransactionData field will be set to nil.

type TransactionOptions

type TransactionOptions struct {
	// TraceContext holds the TraceContext for a new transaction. If this is
	// zero, a new trace will be started.
	TraceContext TraceContext

	// TransactionID holds the ID to assign to the transaction. If this is
	// zero, a new ID will be generated and used instead.
	TransactionID SpanID

	// Start is the start time of the transaction. If this has the
	// zero value, time.Now() will be used instead.
	Start time.Time
}

TransactionOptions holds options for Tracer.StartTransactionOptions.

type WarningLogger

type WarningLogger interface {
	Logger

	// Warningf logs a message at warning level.
	Warningf(format string, args ...interface{})
}

WarningLogger extends Logger with a Warningf method.

TODO(axw) this will be removed in v2.0.0, and the Warningf method will be added directly to Logger.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier