apm

package module
v2.6.2 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2024 License: Apache-2.0 Imports: 49 Imported by: 190

README

Build Status PkgGoDev Go Report Card codecov.io

NOTE: This repository is in maintenance mode. Bug fixes will continue to be applied, but no new features will be implemented. To replace this agent, we recommend you to migrate to the OpenTelemetry Go API and SDK, which provides similar features. In order to help you do a seamless migration, we recommend using our OpenTelemetry Bridge. Please refer to the blog post above for further details.

apm-agent-go: APM Agent for Go

This is the official Go package for Elastic APM.

The Go agent enables you to trace the execution of operations in your application, sending performance metrics and errors to the Elastic APM server.

Installation

Within a Go module:

go get go.elastic.co/apm/v2

Requirements

Requires APM Server v6.5 or newer.

You can find a list of the supported frameworks and other technologies in the documentation.

License

Apache 2.0.

Documentation

Elastic APM Go documentation.

Getting Help

If you find a bug, please report an issue. For any other assistance, please open or add to a topic on the APM discuss forum.

Documentation

Overview

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

Index

Examples

Constants

View Source 
const (
	// AgentVersion is the Elastic APM Go Agent version.
	AgentVersion = "2.6.2"
)

Variables

View Source 
var (
	// OverrideContextWithSpan returns a copy of parent in which the given
	// span is stored, associated with the key ContextSpanKey.
	//
	// OverrideContextWithSpan is a variable to allow other packages, such
	// as apmot, to replace it at package init time.
	OverrideContextWithSpan = defaultContextWithSpan

	// OverrideContextWithTransaction returns a copy of parent in which the
	// given transaction is stored, associated with the key
	// ContextTransactionKey.
	//
	// ContextWithTransaction is a variable to allow other packages, such as
	// apmot, to replace it at package init time.
	OverrideContextWithTransaction = defaultContextWithTransaction

	// OverrideContextWithBodyCapturer returns a copy of parent in which the
	// given body capturer is stored, associated with the key
	// bodyCapturerKey.
	//
	// OverrideContextWithBodyCapturer is a variable to allow other packages,
	// such as apmot, to replace it at package init time.
	OverrideContextWithBodyCapturer = defaultContextWithBodyCapturer

	// OverrideSpanFromContext 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.
	//
	// SpanFromContext is a variable to allow other packages, such as apmot,
	// to replace it at package init time.
	OverrideSpanFromContext = defaultSpanFromContext

	// OverrideTransactionFromContext returns the current Transaction in
	// context, if any. The transaction must have been added to the context
	// previously using ContextWithTransaction.
	//
	// OverrideTransactionFromContext is a variable to allow other packages,
	// such as apmot, to replace it at package init time.
	OverrideTransactionFromContext = defaultTransactionFromContext

	// OverrideBodyCapturerFromContext returns the BodyCapturer in context,
	// if any. The body capturer must have been added to the context
	// previously using ContextWithBodyCapturer.
	//
	// OverrideBodyCapturerFromContext is a variable to allow other
	// packages, such as apmot, to replace it at package init time.
	OverrideBodyCapturerFromContext = defaultBodyCapturerFromContext
)

Functions

func ContextWithBodyCapturer 

func ContextWithBodyCapturer(parent context.Context, bc *BodyCapturer) context.Context

ContextWithBodyCapturer returns a copy of parent in which the given body capturer is stored, associated with the key bodyCapturerKey.

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 SetDefaultTracer 

func SetDefaultTracer(t *Tracer)

SetDefaultTracer sets the tracer returned by DefaultTracer.

If a default tracer has already been initialized, it is closed. Any queued events are not flushed; it is the responsibility of the caller to call the default tracer's Flush method first, if needed.

Calling SetDefaultTracer(nil) will clear the default tracer, causing DefaultTracer to initialize a new default tracer.

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 
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))
})

Output:

Types

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 BodyCapturerFromContext 

func BodyCapturerFromContext(ctx context.Context) *BodyCapturer

BodyCapturerFromContext returns the BodyCapturer in context, if any. The body capturer must have been added to the context previously using ContextWithBodyCapturer.

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 
var ctx context.Context // request context
tx := apm.TransactionFromContext(ctx)
tx.Context.SetCustom("key", "value")

Output:

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. An explicit call to SetUsername always takes precedence.

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.

If, when the transaction ends, its Outcome field has not been explicitly set, it will be set based on the status code: "success" if statusCode < 500, and "failure" otherwise.

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) SetOTelAttributes 

func (c *Context) SetOTelAttributes(m map[string]interface{})

SetOTelAttributes sets the provided OpenTelemetry attributes.

func (*Context) SetOTelSpanKind 

func (c *Context) SetOTelSpanKind(spanKind string)

SetOTelSpanKind sets the provided SpanKind.

func (*Context) SetUserEmail 

func (c *Context) SetUserEmail(email string)

SetUserEmail sets the email for the authenticated user.

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

Output:

func (*Context) SetUserID 

func (c *Context) SetUserID(id string)

SetUserID sets the ID of the authenticated user.

Example 
var ctx context.Context // request context
tx := apm.TransactionFromContext(ctx)
tx.Context.SetUserID("1000")

Output:

func (*Context) SetUsername 

func (c *Context) SetUsername(username string)

SetUsername sets the username of the authenticated user.

Example 
var ctx context.Context // request context
tx := apm.TransactionFromContext(ctx)
tx.Context.SetUsername("root")

Output:

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 DestinationCloudSpanContext 

type DestinationCloudSpanContext struct {
	// Region holds the destination cloud region.
	Region string
}

DestinationCloudSpanContext holds contextual information about a destination cloud.

type DestinationServiceSpanContext 

type DestinationServiceSpanContext struct {
	// Name holds a name for the destination service, which may be used
	// for grouping and labeling in service maps. Deprecated.
	//
	// Deprecated: replaced by `service.target.{type,name}`.
	Name string

	// Resource holds an identifier for a destination service resource,
	// such as a message queue.
	//
	// Deprecated: replaced by `service.target.{type,name}`.
	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.

SetTransaction also has the effect of setting tx's default outcome to "failure", unless it is explicitly specified by the instrumentation.

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{})

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

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

type MessageSpanContext 

type MessageSpanContext struct {
	// QueueName holds the message queue name.
	QueueName string
}

MessageSpanContext holds contextual information about a message.

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.

func (*Metrics) AddHistogram 

func (m *Metrics) AddHistogram(name string, labels []MetricLabel, values []float64, counts []uint64)

AddHistogram adds a histogram metric with the given name, labels, counts, and values. The labels are expected to be sorted lexicographically, and bucket values provided in ascending order.

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 SampleParams 

type SampleParams struct {
	// TraceContext holds the newly-generated TraceContext
	// for the root transaction which is being sampled.
	TraceContext TraceContext
}

SampleParams holds parameters for Sampler.Sample.

type SampleResult 

type SampleResult struct {
	// Sampled holds the sampling decision.
	Sampled bool

	// SampleRate holds the sample rate in effect at the
	// time of the sampling decision. This is used for
	// propagating the value downstream, and for inclusion
	// in events sent to APM Server.
	//
	// The sample rate will be rounded to 4 decimal places
	// half away from zero, except if it is in the interval
	// (0, 0.0001], in which case it is set to 0.0001. The
	// Sampler implementation should also internally apply
	// this logic to ensure consistency.
	SampleRate float64
}

SampleResult holds information about a sampling decision.

type Sampler 

type Sampler interface {
	// Sample indicates whether or not a transaction
	// should be sampled, and the sampling rate in
	// effect at the time.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(SampleParams) SampleResult
}

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.

Sampling rate is rounded to 4 digits half away from zero, except if it is in the interval (0, 0.0001], in which case is set to 0.0001.

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

type ServiceSpanContext added in v2.2.0 

type ServiceSpanContext struct {
	// Target holds the destination service.
	Target *ServiceTargetSpanContext
}

ServiceSpanContext holds contextual information about the service for a span that relates to an operation involving an external service.

type ServiceTargetSpanContext added in v2.2.0 

type ServiceTargetSpanContext struct {
	// Type holds the destination service type.
	Type string

	// Name holds the destination service name.
	Name string
}

ServiceTargetSpanContext fields replace the `span.destination.service.*` fields that are deprecated.

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 (s *Span) AddLink(l SpanLink)

AddLink adds a link.

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) IsExitSpan 

func (s *Span) IsExitSpan() bool

IsExitSpan returns true if the span is an exit span.

func (*Span) ParentID 

func (s *Span) ParentID() SpanID

ParentID returns the ID of the span's parent span or transaction.

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 with an empty addr.

func (*SpanContext) SetDestinationCloud 

func (c *SpanContext) SetDestinationCloud(cloud DestinationCloudSpanContext)

SetDestinationCloud sets the destination cloud info in the context.

func (*SpanContext) SetDestinationService deprecated 

func (c *SpanContext) SetDestinationService(service DestinationServiceSpanContext)

SetDestinationService sets the destination service info in the context.

Both service.Name and service.Resource are required. If either is empty, then SetDestinationService is a no-op.

Deprecated: use SetServiceTarget

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.

If, when the transaction ends, its Outcome field has not been explicitly set, it will be set based on the status code: "success" if statusCode < 400, and "failure" otherwise.

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) SetMessage 

func (c *SpanContext) SetMessage(message MessageSpanContext)

SetMessage sets the message info in the context.

message.Name is required. If it is empty, then SetMessage is a no-op.

func (*SpanContext) SetOTelAttributes 

func (c *SpanContext) SetOTelAttributes(m map[string]interface{})

SetOTelAttributes sets the provided OpenTelemetry attributes.

func (*SpanContext) SetOTelSpanKind 

func (c *SpanContext) SetOTelSpanKind(spanKind string)

SetOTelSpanKind sets the provided SpanKind.

func (*SpanContext) SetServiceTarget added in v2.2.0 

func (c *SpanContext) SetServiceTarget(service ServiceTargetSpanContext)

SetServiceTarget sets the service target info in the context.

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

	// Outcome holds the span outcome: success, failure, or unknown (the default).
	// If Outcome is set to something else, it will be replaced with "unknown".
	//
	// Outcome is used for error rate calculations. A value of "success" indicates
	// that a operation succeeded, while "failure" indicates that the operation
	// failed. If Outcome is set to "unknown" (or some other value), then the
	// span will not be included in error rate calculations.
	Outcome string

	// 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 SpanLink struct {
	Trace TraceID
	Span  SpanID
}

SpanLink describes a linked span.

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

	// Indicates whether a span is an exit span or not. All child spans
	// will be noop spans.
	ExitSpan bool

	// 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

	// Links, if non-nil, holds a list of spans linked to the span.
	Links []SpanLink
	// 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 or if there are too many entries.

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 {
	// 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.

Example

ExampleTracer shows how to use the Tracer API 

// 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/v2"
)

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

	os.Setenv("ELASTIC_APM_SERVER_URL", server.URL)
	defer os.Unsetenv("ELASTIC_APM_SERVER_URL")

	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()
}

Output:

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

func DefaultTracer 

func DefaultTracer() *Tracer

DefaultTracer returns the default global Tracer, set the first time the function is called, or after calling SetDefaultTracer(nil).

The default tracer is configured via environment variables, and if the those are invalid the tracer will be disabled.

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) IgnoredTransactionURL 

func (t *Tracer) IgnoredTransactionURL(url *url.URL) bool

IgnoredTransactionURL returns whether the given transaction URL should be ignored

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) SetContinuationStrategy added in v2.2.0 

func (t *Tracer) SetContinuationStrategy(v string)

SetContinuationStrategy sets the continuation strategy.

func (*Tracer) SetExitSpanMinDuration 

func (t *Tracer) SetExitSpanMinDuration(v time.Duration)

SetExitSpanMinDuration sets the minimum duration for an exit span to not be dropped.

func (*Tracer) SetIgnoreTransactionURLs 

func (t *Tracer) SetIgnoreTransactionURLs(pattern string) error

SetIgnoreTransactionURLs sets the wildcard patterns that will be used to ignore transactions with matching URLs.

func (*Tracer) SetLogger 

func (t *Tracer) SetLogger(logger Logger)

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

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.

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

func (*Tracer) SetSpanCompressionEnabled 

func (t *Tracer) SetSpanCompressionEnabled(v bool)

SetSpanCompressionEnabled enables/disables the span compression feature.

func (*Tracer) SetSpanCompressionExactMatchMaxDuration 

func (t *Tracer) SetSpanCompressionExactMatchMaxDuration(v time.Duration)

SetSpanCompressionExactMatchMaxDuration sets the maximum duration for a span to be compressed with `compression_strategy` == `exact_match`.

func (*Tracer) SetSpanCompressionSameKindMaxDuration 

func (t *Tracer) SetSpanCompressionSameKindMaxDuration(v time.Duration)

SetSpanCompressionSameKindMaxDuration sets the maximum duration for a span to be compressed with `compression_strategy` == `same_kind`.

func (*Tracer) SetSpanStackTraceMinDuration added in v2.2.0 

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

SetSpanStackTraceMinDuration 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, a new HTTP transport will be created from environment
	// variables.
	//
	// 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.
	// If Transport implements the interface below, the tracer will query the
	// APM Server "/" endpoint to obtain the remote major version. Implementers
	// of this interface must cache the remote server version and only refresh
	// on subsequent calls that have `refreshStale` set to true. Implementations
	// must be concurrently safe.
	//   MajorServerVersion(ctx context.Context, refreshStale bool) uint32
	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 {
	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 (tx *Transaction) AddLink(l SpanLink)

AddLink adds a link.

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 
// When environment variables aren't set, the default tracer is inactive.
// For the sake of this example, we want a discarded tracer instead, so we do
// have trace and span IDs generated.
//
// This setup is now something you should be using in your own code.
apm.SetDefaultTracer(apmtest.NewDiscardTracer())

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)
}

Output:

<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) 
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)
}

Output:

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

func (*Transaction) ParentID 

func (tx *Transaction) ParentID() SpanID

ParentID returns the ID of the transaction's Parent or a zero (invalid) SpanID.

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) StartExitSpan added in v2.2.0 

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

StartExitSpan 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.

StartExitSpan 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.

StartExitSpan is equivalent to calling StartSpanOptions with SpanOptions.Parent set to the trace context of parent if parent is non-nil and the span being marked as an exit span.

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

	// Outcome holds the transaction outcome: success, failure, or
	// unknown (the default). If Outcome is set to something else,
	// it will be replaced with "unknown".
	//
	// Outcome is used for error rate calculations. A value of "success"
	// indicates that a transaction succeeded, while "failure" indicates
	// that the transaction failed. If Outcome is set to "unknown" (or
	// some other value), then the transaction will not be included in
	// error rate calculations.
	Outcome 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

	// Links, if non-nil, holds a list of spans linked to the transaction.
	Links []SpanLink
}

TransactionOptions holds options for Tracer.StartTransactionOptions.

Source Files

View all Source files

Directories

Path Synopsis
Package apmconfig provides an API for watching agent config changes.
 Package apmconfig provides an API for watching agent config changes.
internal
apmcloudutil
apmhostutil
apmhttputil
apmlog
apmstrings
apmversion
configutil
iochan
Package iochan provides a channel-based io.Reader.
 Package iochan provides a channel-based io.Reader.
ringbuffer
Package ringbuffer provides a ring buffer for storing blocks of bytes.
 Package ringbuffer provides a ring buffer for storing blocks of bytes.
wildcard
Package wildcard provides a fast, zero-allocation wildcard matcher.
 Package wildcard provides a fast, zero-allocation wildcard matcher.
Package model provides the Elastic APM model types.
 Package model provides the Elastic APM model types.
Package sqlutil provides utilities to SQL-related instrumentation modules.
 Package sqlutil provides utilities to SQL-related instrumentation modules.
Package stacktrace provides a simplified stack frame type, functions for obtaining stack frames, and related utilities.
 Package stacktrace provides a simplified stack frame type, functions for obtaining stack frames, and related utilities.
Package transport provides an interface and implementation for transporting data to the Elastic APM server.
 Package transport provides an interface and implementation for transporting data to the Elastic APM server.
transporttest
Package transporttest provides implementations of transport.Transport for testing purposes.
 Package transporttest provides implementations of transport.Transport for testing purposes.

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.