README

Build Status PkgGoDev Go Report Card codecov.io

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. You can find a list of the supported frameworks and other technologies in the documentation.

We'd love to hear your feedback, please take a minute to fill out our survey.

Installation

go get -u go.elastic.co/apm

Requirements

Tested with Go 1.8+ on Linux, Windows and MacOS.

Requires APM Server v6.5 or newer.

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 = "1.11.0"
    )

    Variables

    This section is empty.

    Functions

    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
                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 (*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
                          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.

                              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) 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
                                          Output:
                                          
                                          

                                          func (*Context) SetUserID

                                          func (c *Context) SetUserID(id string)

                                            SetUserID sets the ID of the authenticated user.

                                            Example
                                            Output:
                                            
                                            

                                            func (*Context) SetUsername

                                            func (c *Context) SetUsername(username string)

                                              SetUsername sets the username of the authenticated user.

                                              Example
                                              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 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 ExtendedSampler

                                                                                    type ExtendedSampler interface {
                                                                                    	// SampleExtended 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.
                                                                                    	SampleExtended(SampleParams) SampleResult
                                                                                    }

                                                                                      ExtendedSampler may be implemented by Samplers, providing a method for sampling and returning an extended SampleResult.

                                                                                      TODO(axw) in v2.0.0, replace the Sampler interface with this.

                                                                                      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 SampleParams

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

                                                                                                      SampleParams holds parameters for SampleExtended.

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

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

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

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

                                                                                                                                                                                            NOTE when this package is imported, DefaultTracer is initialised using environment variables for configuration. When creating a tracer with NewTracer or NewTracerOptions, you should close apm.DefaultTracer if it is not needed, e.g. by calling apm.DefaultTracer.Close() in an init function.

                                                                                                                                                                                            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.

                                                                                                                                                                                              NOTE when this package is imported, DefaultTracer is initialised using environment variables for configuration. When creating a tracer with NewTracer or NewTracerOptions, you should close apm.DefaultTracer if it is not needed, e.g. by calling apm.DefaultTracer.Close() in an init function.

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

                                                                                                                                                                                                                                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.

                                                                                                                                                                                                                                            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) 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
                                                                                                                                                                                                                                                                          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)
                                                                                                                                                                                                                                                                          Output:
                                                                                                                                                                                                                                                                          
                                                                                                                                                                                                                                                                          <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
                                                                                                                                                                                                                                                                                    
                                                                                                                                                                                                                                                                                    	// 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
                                                                                                                                                                                                                                                                                      }

                                                                                                                                                                                                                                                                                        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.

                                                                                                                                                                                                                                                                                          Directories

                                                                                                                                                                                                                                                                                          Path Synopsis
                                                                                                                                                                                                                                                                                          Package apmconfig provides an API for watching agent config changes.
                                                                                                                                                                                                                                                                                          Package apmconfig provides an API for watching agent config changes.
                                                                                                                                                                                                                                                                                          Package model provides the Elastic APM model types.
                                                                                                                                                                                                                                                                                          Package model provides the Elastic APM model types.
                                                                                                                                                                                                                                                                                          module
                                                                                                                                                                                                                                                                                          apmawssdkgo Module
                                                                                                                                                                                                                                                                                          apmbeego Module
                                                                                                                                                                                                                                                                                          apmchi Module
                                                                                                                                                                                                                                                                                          apmchiv5 Module
                                                                                                                                                                                                                                                                                          apmecho Module
                                                                                                                                                                                                                                                                                          apmechov4 Module
                                                                                                                                                                                                                                                                                          apmgin Module
                                                                                                                                                                                                                                                                                          apmgocql Module
                                                                                                                                                                                                                                                                                          apmgokit Module
                                                                                                                                                                                                                                                                                          apmgometrics Module
                                                                                                                                                                                                                                                                                          apmgopg Module
                                                                                                                                                                                                                                                                                          apmgopgv10 Module
                                                                                                                                                                                                                                                                                          apmgoredis Module
                                                                                                                                                                                                                                                                                          apmgoredisv8 Module
                                                                                                                                                                                                                                                                                          apmgorilla Module
                                                                                                                                                                                                                                                                                          apmgorm Module
                                                                                                                                                                                                                                                                                          apmgormv2 Module
                                                                                                                                                                                                                                                                                          apmgrpc Module
                                                                                                                                                                                                                                                                                          apmhttp Module
                                                                                                                                                                                                                                                                                          apmhttprouter Module
                                                                                                                                                                                                                                                                                          apmlambda Module
                                                                                                                                                                                                                                                                                          apmlogrus Module
                                                                                                                                                                                                                                                                                          apmmongo Module
                                                                                                                                                                                                                                                                                          apmnegroni Module
                                                                                                                                                                                                                                                                                          apmot Module
                                                                                                                                                                                                                                                                                          apmprometheus Module
                                                                                                                                                                                                                                                                                          apmredigo Module
                                                                                                                                                                                                                                                                                          apmrestful Module
                                                                                                                                                                                                                                                                                          apmsql Module
                                                                                                                                                                                                                                                                                          apmzap Module
                                                                                                                                                                                                                                                                                          apmzerolog Module
                                                                                                                                                                                                                                                                                          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.
                                                                                                                                                                                                                                                                                          internal
                                                                                                                                                                                                                                                                                          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.
                                                                                                                                                                                                                                                                                          sqlutil
                                                                                                                                                                                                                                                                                          Package sqlutil provides utilities to SQL-related instrumentation modules.
                                                                                                                                                                                                                                                                                          Package sqlutil provides utilities to SQL-related instrumentation modules.
                                                                                                                                                                                                                                                                                          wildcard
                                                                                                                                                                                                                                                                                          Package wildcard provides a fast, zero-allocation wildcard matcher.
                                                                                                                                                                                                                                                                                          Package wildcard provides a fast, zero-allocation wildcard matcher.