Back to godoc.org
github.com/elastic/apm-agent-go

Package elasticapm

v0.5.2
Latest Go to latest
Published: Sep 20, 2018 | License: Apache-2.0 | Module: github.com/elastic/apm-agent-go

Overview

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

Index

Examples

Package Files

Constants

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

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.

type BodyCapturer

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

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

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.

func (*Context) SetCustom

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

SetCustom sets a custom context key/value pair. If the key is invalid (contains '.', '*', or '"'), the call is a no-op. The value must be JSON-encodable.

If value implements interface{AppendJSON([]byte) []byte}, that will be used to encode the value. Otherwise, value will be encoded using json.Marshal. As a special case, values of type map[string]interface{} will be traversed and values encoded according to the same rules.

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

func (c *Context) SetHTTPResponseFinished(finished bool)

SetHTTPResponseFinished records whether or not the response was finished.

func (*Context) SetHTTPResponseHeaders

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

SetHTTPResponseHeaders sets the HTTP response headers in the context.

func (*Context) SetHTTPResponseHeadersSent

func (c *Context) SetHTTPResponseHeadersSent(headersSent bool)

SetHTTPResponseHeadersSent records whether or not response were sent.

func (*Context) SetHTTPStatusCode

func (c *Context) SetHTTPStatusCode(statusCode int)

SetHTTPStatusCode records the HTTP response status code.

func (*Context) SetTag

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

SetTag sets a tag in the context. If the key is invalid (contains '.', '*', or '"'), the call is a no-op.

func (*Context) SetUserEmail

func (c *Context) SetUserEmail(email string)

SetUserEmail sets the email for the authenticated user.

func (*Context) SetUserID

func (c *Context) SetUserID(id string)

SetUserID sets the ID of the authenticated user.

func (*Context) SetUsername

func (c *Context) SetUsername(username string)

SetUsername sets the username of the authenticated user.

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 Error

type Error struct {

	// ID is the unique ID of the error. This is set by NewError,
	// and can be used for correlating errors and log records.
	ID ErrorID

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

	// Transaction is the transaction to which the error correspoonds,
	// if any. If this is set, the error's Send method must be called
	// before the transaction's End method.
	Transaction *Transaction

	// 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
	// only applies to "exception" errors (errors created with
	// NewError, or Recovered), and is ignored by "log" errors.
	Handled bool

	// Context holds the context for this error.
	Context Context
	// 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 present in the context, if any, and calls its SetException method with the given error. The Error.Handled field will be set to true, and a stacktrace set.

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

func (*Error) Send

func (e *Error) Send()

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

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.

type ErrorID

type ErrorID [16]byte

ErrorID uniquely identifies an error.

func (ErrorID) String

func (id ErrorID) String() string

String returns id in the canonical v4 UUID 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
}

ErrorLogRecord holds details of an error log record.

type GatherMetricsFunc

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

GatherMetricsFunc is a function type implementing MetricsGatherer.

func (GatherMetricsFunc) GatherMetrics

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

GatherMetrics calls f(ctx, m).

type Logger

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

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

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

type MetricLabel

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

	// Value is the label value.
	Value string
}

MetricLabel is a name/value pair for labeling metrics.

type Metrics

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

Metrics holds a set of metrics.

func (*Metrics) Add

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

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

type MetricsGatherer

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

MetricsGatherer provides an interface for gathering metrics.

type RatioSampler

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

RatioSampler is a Sampler that samples probabilistically based on the given ratio within the range [0,1.0].

A ratio of 1.0 samples 100% of transactions, a ratio of 0.5 samples ~50%, and so on.

func NewRatioSampler

func NewRatioSampler(r float64, source rand.Source) *RatioSampler

NewRatioSampler returns a new RatioSampler with the given ratio and math/rand.Source. The source will be called from multiple goroutines, but the sampler will internally synchronise access to it; the source should not be used by any other goroutines.

If the ratio provided does not lie within the range [0,1.0], NewRatioSampler will panic.

func (*RatioSampler) Sample

func (s *RatioSampler) Sample(*Transaction) bool

Sample samples the transaction according to the configured ratio and pseudo-random source.

type Sampler

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

Sampler provides a means of sampling transactions.

type Span

type Span struct {
	Name      string
	Type      string
	Timestamp time.Time
	Duration  time.Duration
	Context   SpanContext
	// 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 either ContextWithSpan or SetSpanInContext.

func StartSpan

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

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

StartSpan 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 s.Timestamp.

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: its trace ID, span ID, and trace options. The values are undefined if distributed tracing is disabled. If the span is dropped, the trace ID and options will be zero.

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

type SpanID

type SpanID [8]byte

SpanID identifies a span within a trace.

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

TraceContext holds trace context for an incoming or outgoing request.

type TraceID

type TraceID [16]byte

TraceID identifies a trace forest.

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

func (o TraceOptions) MaybeRecorded() bool

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

func (TraceOptions) Requested

func (o TraceOptions) Requested() bool

Requested reports whether or not it has been requested that this transaction/span be recorded.

func (TraceOptions) WithMaybeRecorded

func (o TraceOptions) WithMaybeRecorded(maybeRecorded bool) TraceOptions

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

func (TraceOptions) WithRequested

func (o TraceOptions) WithRequested(requested bool) TraceOptions

WithRequested changes the "requested" flag, and returns the new options without modifying the original value.

type Tracer

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

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

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

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

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

Example

ExampleTracer shows how to use the Tracer API

Code:

package elasticapm_test

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

	"github.com/elastic/apm-agent-go"
	"github.com/elastic/apm-agent-go/transport"
)

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

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

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

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

	// The tracer will queue transactions to be sent at a later time,
	// or when the queue becomes full. The interval and queue size
	// can both be configured by setting the environment variables
	// ELASTIC_APM_FLUSH_INTERVAL and ELASTIC_APM_MAX_QUEUE_SIZE
	// respectively. Alternatively, the tracer's SetFlushInterval
	// and SetMaxQueueSize methods can be used.
	tracer.Flush(nil)

	fmt.Println("number of payloads:", len(r.payloads))
	p0 := r.payloads[0]
	service := p0["service"].(map[string]interface{})
	agent := service["agent"].(map[string]interface{})
	language := service["language"].(map[string]interface{})
	runtime := service["runtime"].(map[string]interface{})
	transactions := p0["transactions"].([]interface{})
	fmt.Println("  service name:", service["name"])
	fmt.Println("  service version:", service["version"])
	fmt.Println("  agent name:", agent["name"])
	fmt.Println("  language name:", language["name"])
	fmt.Println("  runtime name:", runtime["name"])
	fmt.Println("  number of transactions:", len(transactions))
	for i := range transactions {
		t := transactions[i].(map[string]interface{})
		fmt.Println("    transaction name:", t["name"])
		fmt.Println("    transaction type:", t["type"])
		fmt.Println("    transaction context:", t["context"])
		spans := t["spans"].([]interface{})
		fmt.Println("    number of spans:", len(spans))
		s0 := spans[0].(map[string]interface{})
		fmt.Println("      span name:", s0["name"])
		fmt.Println("      span type:", s0["type"])
	}

	// Output:
	// number of payloads: 1
	//   service name: service-name
	//   service version: 1.0.0
	//   agent name: go
	//   language name: go
	//   runtime name: gc
	//   number of transactions: 2
	//     transaction name: order
	//     transaction type: request
	//     transaction context: map[custom:map[product:fish fingers]]
	//     number of spans: 1
	//       span name: store_order
	//       span type: rpc
	//     transaction name: order
	//     transaction type: request
	//     transaction context: map[custom:map[product:detergent]]
	//     number of spans: 1
	//       span name: store_order
	//       span type: rpc
}

type api struct {
	tracer *elasticapm.Tracer
}

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

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

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

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

	time.Sleep(50 * time.Millisecond)
}

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

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

func (r *recorder) ServeHTTP(w http.ResponseWriter, req *http.Request) {
	var body io.Reader = req.Body
	if req.Header.Get("Content-Encoding") == "gzip" {
		r, err := gzip.NewReader(body)
		if err != nil {
			panic(err)
		}
		body = r
	}
	var m map[string]interface{}
	if err := json.NewDecoder(body).Decode(&m); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
	}
	r.mu.Lock()
	r.payloads = append(r.payloads, m)
	r.mu.Unlock()
}
number of payloads: 1
  service name: service-name
  service version: 1.0.0
  agent name: go
  language name: go
  runtime name: gc
  number of transactions: 2
    transaction name: order
    transaction type: request
    transaction context: map[custom:map[product:fish fingers]]
    number of spans: 1
      span name: store_order
      span type: rpc
    transaction name: order
    transaction type: request
    transaction context: map[custom:map[product:detergent]]
    number of spans: 1
      span name: store_order
      span 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, initializing a Service with the specified name and version, or taking the service name and version from the environment if unspecified.

If serviceName is empty, then the service name will be defined using the ELASTIC_APM_SERVER_NAME environment variable.

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.

func (*Tracer) Close

func (t *Tracer) Close()

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

func (*Tracer) Flush

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

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

func (*Tracer) NewError

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

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

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

If err implements

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

or

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

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

If err implements

type interface {Type() string}

then that will be used to set the error type.

If err implements

type interface {Code() string}

or

type interface {Code() float64}

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

func (*Tracer) NewErrorLog

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

NewErrorLog returns a new Error for the given ErrorLogRecord.

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

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

func (*Tracer) Recover

func (t *Tracer) Recover(tx *Transaction)

Recover recovers panics, sending them as errors to the Elastic APM server. Recover is expected to be used in a deferred call.

Recover simply calls t.Recovered(v, tx), where v is the recovered value, and then calls the resulting Error's Send method.

func (*Tracer) Recovered

func (t *Tracer) Recovered(v interface{}, tx *Transaction) *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.

The resulting error's Transaction will be set to tx,

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

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

SetFlushInterval sets the flush interval -- the amount of time to wait before flushing enqueued transactions to the APM server.

func (*Tracer) SetLogger

func (t *Tracer) SetLogger(logger Logger)

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

func (*Tracer) SetMaxErrorQueueSize

func (t *Tracer) SetMaxErrorQueueSize(n int)

SetMaxErrorQueueSize sets the maximum error queue size -- the maximum number of errors to buffer before they will start getting dropped. If set to a non-positive value, the queue size is unlimited.

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. If set to a non-positive value, the number of spans is unlimited.

func (*Tracer) SetMaxTransactionQueueSize

func (t *Tracer) SetMaxTransactionQueueSize(n int)

SetMaxTransactionQueueSize sets the maximum transaction queue size -- the maximum number of transactions to buffer before flushing to the APM server. If set to a non-positive value, the queue size is unlimited.

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

func (*Tracer) SetSanitizedFieldNames

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

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

func (*Tracer) SetSpanFramesMinDuration

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

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

func (*Tracer) 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 TracerStats

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

TracerStats holds statistics for a Tracer.

type TracerStatsErrors

type TracerStatsErrors struct {
	SetContext       uint64
	SendTransactions uint64
	SendErrors       uint64
}

TracerStatsErrors holds error statistics for a Tracer.

type Transaction

type Transaction struct {
	Name      string
	Type      string
	Timestamp time.Time
	Duration  time.Duration
	Context   Context
	Result    string
	// 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 either ContextWithTransaction or SetTransactionInContext.

func (*Transaction) Discard

func (tx *Transaction) Discard()

Discard discards a previously started transaction. The Transaction must not be used after this.

func (*Transaction) End

func (tx *Transaction) End()

End enqueues tx for sending to the Elastic APM server; tx must not be used after this.

If tx.Duration has not been set, End will set it to the elapsed time since tx.Timestamp.

func (*Transaction) Sampled

func (tx *Transaction) Sampled() bool

Sampled reports whether or not the transaction is sampled.

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 relative to the transaction's timestamp.

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

func (*Transaction) TraceContext

func (tx *Transaction) TraceContext() TraceContext

TraceContext returns the transaction's TraceContext: its trace ID, span ID, and trace options. The values are undefined if distributed tracing is disabled.

type TransactionOptions

type TransactionOptions struct {
	// TraceContext holds the TraceContext for a new transaction. If this is
	// zero, and distributed tracing is enabled, a new trace will be started.
	//
	// TraceContext is ignored if distributed tracing is disabled.
	TraceContext TraceContext

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

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

Jump to identifier

Keyboard shortcuts

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