sentry

package module
v0.30.0 Latest Latest
Warning

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

Go to latest
Published: Dec 3, 2024 License: MIT Imports: 37 Imported by: 2,794

README

Sentry

Official Sentry SDK for Go

Build Status Go Report Card Discord go.dev

sentry-go provides a Sentry client implementation for the Go programming language. This is the next generation of the Go SDK for Sentry, intended to replace the raven-go package.

Looking for the old raven-go SDK documentation? See the Legacy client section here. If you want to start using sentry-go instead, check out the migration guide.

Requirements

The only requirement is a Go compiler.

We verify this package against the 3 most recent releases of Go. Those are the supported versions. The exact versions are defined in GitHub workflow.

In addition, we run tests against the current master branch of the Go toolchain, though support for this configuration is best-effort.

Installation

sentry-go can be installed like any other Go library through go get:

$ go get github.com/getsentry/sentry-go@latest

Check out the list of released versions.

Configuration

To use sentry-go, you’ll need to import the sentry-go package and initialize it with your DSN and other options.

If not specified in the SDK initialization, the DSN, Release and Environment are read from the environment variables SENTRY_DSN, SENTRY_RELEASE and SENTRY_ENVIRONMENT, respectively.

More on this in the Configuration section of the official Sentry Go SDK documentation.

Usage

The SDK supports reporting errors and tracking application performance.

To get started, have a look at one of our examples:

We also provide a complete API reference.

For more detailed information about how to get the most out of sentry-go, checkout the official documentation:

Resources

License

Licensed under The MIT License, see LICENSE.

Community

Join Sentry's #go channel on Discord to get involved and help us improve the SDK!

Documentation

Overview

Package repository: https://github.com/getsentry/sentry-go/

For more information about Sentry and SDK features, please have a look at the official documentation site: https://docs.sentry.io/platforms/go/

Example (TransportWithHooks)

Initializing the SDK with a custom HTTP transport gives a lot of flexibility to inspect requests and responses. This example adds before and after hooks.

package main

import (
	"fmt"
	"net/http"
	"net/http/httputil"
	"os"
	"time"

	"github.com/getsentry/sentry-go"
)

// TransportWithHooks is an http.RoundTripper that wraps an existing
// http.RoundTripper adding hooks that run before and after each round trip.
type TransportWithHooks struct {
	http.RoundTripper
	Before func(*http.Request) error
	After  func(*http.Request, *http.Response, error) (*http.Response, error)
}

func (t *TransportWithHooks) RoundTrip(req *http.Request) (*http.Response, error) {
	if err := t.Before(req); err != nil {
		return nil, err
	}
	resp, err := t.RoundTripper.RoundTrip(req)
	return t.After(req, resp, err)
}

// Initializing the SDK with a custom HTTP transport gives a lot of flexibility
// to inspect requests and responses. This example adds before and after hooks.
func main() {
	err := sentry.Init(sentry.ClientOptions{
		// Either set your DSN here or set the SENTRY_DSN environment variable.
		Dsn:   "",
		Debug: true,
		HTTPTransport: &TransportWithHooks{
			RoundTripper: http.DefaultTransport,
			Before: func(req *http.Request) error {
				if b, err := httputil.DumpRequestOut(req, true); err != nil {
					fmt.Println(err)
				} else {
					fmt.Printf("%s\n", b)
				}
				return nil
			},
			After: func(req *http.Request, resp *http.Response, err error) (*http.Response, error) {
				if b, err := httputil.DumpResponse(resp, true); err != nil {
					fmt.Println(err)
				} else {
					fmt.Printf("%s\n", b)
				}
				return resp, err
			},
		},
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "sentry.Init: %s\n", err)
		os.Exit(1)
	}
	defer sentry.Flush(2 * time.Second)

	sentry.CaptureMessage("test")
}
Output:

Index

Examples

Constants

View Source
const (
	// HubContextKey is the key used to store the current Hub.
	HubContextKey = contextKey(1)
	// RequestContextKey is the key used to store the current http.Request.
	RequestContextKey = contextKey(2)
)

Keys used to store values in a Context. Use with Context.Value to access values stored by the SDK.

View Source
const (
	SentryTraceHeader   = "sentry-trace"
	SentryBaggageHeader = "baggage"
)
View Source
const (
	SpanOriginManual   = "manual"
	SpanOriginEcho     = "auto.http.echo"
	SpanOriginFastHTTP = "auto.http.fasthttp"
	SpanOriginFiber    = "auto.http.fiber"
	SpanOriginGin      = "auto.http.gin"
	SpanOriginStdLib   = "auto.http.stdlib"
	SpanOriginIris     = "auto.http.iris"
	SpanOriginNegroni  = "auto.http.negroni"
)
View Source
const SDKVersion = "0.30.0"

The version of the SDK.

Variables

View Source
var Logger = log.New(io.Discard, "[Sentry] ", log.LstdFlags)

Logger is an instance of log.Logger that is use to provide debug information about running Sentry Client can be enabled by either using Logger.SetOutput directly or with Debug client option.

Functions

func AddBreadcrumb

func AddBreadcrumb(breadcrumb *Breadcrumb)

AddBreadcrumb records a new breadcrumb.

The total number of breadcrumbs that can be recorded are limited by the configuration on the client.

func AddGlobalEventProcessor

func AddGlobalEventProcessor(processor EventProcessor)

AddGlobalEventProcessor adds processor to the global list of event processors. Global event processors apply to all events.

AddGlobalEventProcessor is deprecated. Most users will prefer to initialize the SDK with Init and provide a ClientOptions.BeforeSend function or use Scope.AddEventProcessor instead.

func ConfigureScope

func ConfigureScope(f func(scope *Scope))

ConfigureScope is a shorthand for CurrentHub().ConfigureScope.

func Flush

func Flush(timeout time.Duration) bool

Flush waits until the underlying Transport sends any buffered events to the Sentry server, blocking for at most the given timeout. It returns false if the timeout was reached. In that case, some events may not have been sent.

Flush should be called before terminating the program to avoid unintentionally dropping events.

Do not call Flush indiscriminately after every call to CaptureEvent, CaptureException or CaptureMessage. Instead, to have the SDK send events over the network synchronously, configure it to use the HTTPSyncTransport in the call to Init.

func HasHubOnContext

func HasHubOnContext(ctx context.Context) bool

HasHubOnContext checks whether Hub instance is bound to a given Context struct.

func Init

func Init(options ClientOptions) error

Init initializes the SDK with options. The returned error is non-nil if options is invalid, for instance if a malformed DSN is provided.

func Pointer added in v0.28.0

func Pointer[T any](v T) *T

func PopScope

func PopScope()

PopScope is a shorthand for CurrentHub().PopScope.

func PushScope

func PushScope()

PushScope is a shorthand for CurrentHub().PushScope.

func SetHubOnContext

func SetHubOnContext(ctx context.Context, hub *Hub) context.Context

SetHubOnContext stores given Hub instance on the Context struct and returns a new Context.

func WithScope

func WithScope(f func(scope *Scope))

WithScope is a shorthand for CurrentHub().WithScope.

Types

type Attachment added in v0.23.0

type Attachment struct {
	Filename    string
	ContentType string
	Payload     []byte
}

Attachment allows associating files with your events to aid in investigation. An event may contain one or more attachments.

type Breadcrumb struct {
	Type      string                 `json:"type,omitempty"`
	Category  string                 `json:"category,omitempty"`
	Message   string                 `json:"message,omitempty"`
	Data      map[string]interface{} `json:"data,omitempty"`
	Level     Level                  `json:"level,omitempty"`
	Timestamp time.Time              `json:"timestamp"`
}

Breadcrumb specifies an application event that occurred before a Sentry event. An event may contain one or more breadcrumbs.

func (b *Breadcrumb) MarshalJSON() ([]byte, error)

MarshalJSON converts the Breadcrumb struct to JSON.

type BreadcrumbHint map[string]interface{}

BreadcrumbHint contains information that can be associated with a Breadcrumb.

type CheckIn added in v0.23.0

type CheckIn struct {
	// Check-In ID (unique and client generated)
	ID EventID `json:"check_in_id"`
	// The distinct slug of the monitor.
	MonitorSlug string `json:"monitor_slug"`
	// The status of the check-in.
	Status CheckInStatus `json:"status"`
	// The duration of the check-in. Will only take effect if the status is ok or error.
	Duration time.Duration `json:"duration,omitempty"`
}

type CheckInStatus added in v0.23.0

type CheckInStatus string
const (
	CheckInStatusInProgress CheckInStatus = "in_progress"
	CheckInStatusOK         CheckInStatus = "ok"
	CheckInStatusError      CheckInStatus = "error"
)

type Client

type Client struct {

	// Transport is read-only. Replacing the transport of an existing client is
	// not supported, create a new client instead.
	Transport Transport
	// contains filtered or unexported fields
}

Client is the underlying processor that is used by the main API and Hub instances. It must be created with NewClient.

func NewClient

func NewClient(options ClientOptions) (*Client, error)

NewClient creates and returns an instance of Client configured using ClientOptions.

Most users will not create clients directly. Instead, initialize the SDK with Init and use the package-level functions (for simple programs that run on a single goroutine) or hub methods (for concurrent programs, for example web servers).

func (*Client) AddEventProcessor

func (client *Client) AddEventProcessor(processor EventProcessor)

AddEventProcessor adds an event processor to the client. It must not be called from concurrent goroutines. Most users will prefer to use ClientOptions.BeforeSend or Scope.AddEventProcessor instead.

Note that typical programs have only a single client created by Init and the client is shared among multiple hubs, one per goroutine, such that adding an event processor to the client affects all hubs that share the client.

func (*Client) CaptureCheckIn added in v0.23.0

func (client *Client) CaptureCheckIn(checkIn *CheckIn, monitorConfig *MonitorConfig, scope EventModifier) *EventID

CaptureCheckIn captures a check in.

func (*Client) CaptureEvent

func (client *Client) CaptureEvent(event *Event, hint *EventHint, scope EventModifier) *EventID

CaptureEvent captures an event on the currently active client if any.

The event must already be assembled. Typically code would instead use the utility methods like CaptureException. The return value is the event ID. In case Sentry is disabled or event was dropped, the return value will be nil.

func (*Client) CaptureException

func (client *Client) CaptureException(exception error, hint *EventHint, scope EventModifier) *EventID

CaptureException captures an error.

func (*Client) CaptureMessage

func (client *Client) CaptureMessage(message string, hint *EventHint, scope EventModifier) *EventID

CaptureMessage captures an arbitrary message.

func (*Client) EventFromCheckIn added in v0.23.0

func (client *Client) EventFromCheckIn(checkIn *CheckIn, monitorConfig *MonitorConfig) *Event

EventFromCheckIn creates a new Sentry event from the given `check_in` instance.

func (*Client) EventFromException added in v0.21.0

func (client *Client) EventFromException(exception error, level Level) *Event

EventFromException creates a new Sentry event from the given `error` instance.

func (*Client) EventFromMessage added in v0.21.0

func (client *Client) EventFromMessage(message string, level Level) *Event

EventFromMessage creates an event from the given message string.

func (*Client) Flush

func (client *Client) Flush(timeout time.Duration) bool

Flush waits until the underlying Transport sends any buffered events to the Sentry server, blocking for at most the given timeout. It returns false if the timeout was reached. In that case, some events may not have been sent.

Flush should be called before terminating the program to avoid unintentionally dropping events.

Do not call Flush indiscriminately after every call to CaptureEvent, CaptureException or CaptureMessage. Instead, to have the SDK send events over the network synchronously, configure it to use the HTTPSyncTransport in the call to Init.

func (*Client) GetSDKIdentifier added in v0.24.0

func (client *Client) GetSDKIdentifier() string

func (*Client) Options

func (client *Client) Options() ClientOptions

Options return ClientOptions for the current Client.

func (*Client) Recover

func (client *Client) Recover(err interface{}, hint *EventHint, scope EventModifier) *EventID

Recover captures a panic. Returns EventID if successfully, or nil if there's no error to recover from.

func (*Client) RecoverWithContext

func (client *Client) RecoverWithContext(
	ctx context.Context,
	err interface{},
	hint *EventHint,
	scope EventModifier,
) *EventID

RecoverWithContext captures a panic and passes relevant context object. Returns EventID if successfully, or nil if there's no error to recover from.

func (*Client) SetSDKIdentifier added in v0.24.0

func (client *Client) SetSDKIdentifier(identifier string)

type ClientOptions

type ClientOptions struct {
	// The DSN to use. If the DSN is not set, the client is effectively
	// disabled.
	Dsn string
	// In debug mode, the debug information is printed to stdout to help you
	// understand what sentry is doing.
	Debug bool
	// Configures whether SDK should generate and attach stacktraces to pure
	// capture message calls.
	AttachStacktrace bool
	// The sample rate for event submission in the range [0.0, 1.0]. By default,
	// all events are sent. Thus, as a historical special case, the sample rate
	// 0.0 is treated as if it was 1.0. To drop all events, set the DSN to the
	// empty string.
	SampleRate float64
	// Enable performance tracing.
	EnableTracing bool
	// The sample rate for sampling traces in the range [0.0, 1.0].
	TracesSampleRate float64
	// Used to customize the sampling of traces, overrides TracesSampleRate.
	TracesSampler TracesSampler
	// The sample rate for profiling traces in the range [0.0, 1.0].
	// This is relative to TracesSampleRate - it is a ratio of profiled traces out of all sampled traces.
	ProfilesSampleRate float64
	// List of regexp strings that will be used to match against event's message
	// and if applicable, caught errors type and value.
	// If the match is found, then a whole event will be dropped.
	IgnoreErrors []string
	// List of regexp strings that will be used to match against a transaction's
	// name.  If a match is found, then the transaction  will be dropped.
	IgnoreTransactions []string
	// If this flag is enabled, certain personally identifiable information (PII) is added by active integrations.
	// By default, no such data is sent.
	SendDefaultPII bool
	// BeforeSend is called before error events are sent to Sentry.
	// Use it to mutate the event or return nil to discard the event.
	BeforeSend func(event *Event, hint *EventHint) *Event
	// BeforeSendTransaction is called before transaction events are sent to Sentry.
	// Use it to mutate the transaction or return nil to discard the transaction.
	BeforeSendTransaction func(event *Event, hint *EventHint) *Event
	// Before breadcrumb add callback.
	BeforeBreadcrumb func(breadcrumb *Breadcrumb, hint *BreadcrumbHint) *Breadcrumb
	// Integrations to be installed on the current Client, receives default
	// integrations.
	Integrations func([]Integration) []Integration
	// io.Writer implementation that should be used with the Debug mode.
	DebugWriter io.Writer
	// The transport to use. Defaults to HTTPTransport.
	Transport Transport
	// The server name to be reported.
	ServerName string
	// The release to be sent with events.
	//
	// Some Sentry features are built around releases, and, thus, reporting
	// events with a non-empty release improves the product experience. See
	// https://docs.sentry.io/product/releases/.
	//
	// If Release is not set, the SDK will try to derive a default value
	// from environment variables or the Git repository in the working
	// directory.
	//
	// If you distribute a compiled binary, it is recommended to set the
	// Release value explicitly at build time. As an example, you can use:
	//
	// 	go build -ldflags='-X main.release=VALUE'
	//
	// That will set the value of a predeclared variable 'release' in the
	// 'main' package to 'VALUE'. Then, use that variable when initializing
	// the SDK:
	//
	// 	sentry.Init(ClientOptions{Release: release})
	//
	// See https://golang.org/cmd/go/ and https://golang.org/cmd/link/ for
	// the official documentation of -ldflags and -X, respectively.
	Release string
	// The dist to be sent with events.
	Dist string
	// The environment to be sent with events.
	Environment string
	// Maximum number of breadcrumbs
	// when MaxBreadcrumbs is negative then ignore breadcrumbs.
	MaxBreadcrumbs int
	// Maximum number of spans.
	//
	// See https://develop.sentry.dev/sdk/envelopes/#size-limits for size limits
	// applied during event ingestion. Events that exceed these limits might get dropped.
	MaxSpans int
	// An optional pointer to http.Client that will be used with a default
	// HTTPTransport. Using your own client will make HTTPTransport, HTTPProxy,
	// HTTPSProxy and CaCerts options ignored.
	HTTPClient *http.Client
	// An optional pointer to http.Transport that will be used with a default
	// HTTPTransport. Using your own transport will make HTTPProxy, HTTPSProxy
	// and CaCerts options ignored.
	HTTPTransport http.RoundTripper
	// An optional HTTP proxy to use.
	// This will default to the HTTP_PROXY environment variable.
	HTTPProxy string
	// An optional HTTPS proxy to use.
	// This will default to the HTTPS_PROXY environment variable.
	// HTTPS_PROXY takes precedence over HTTP_PROXY for https requests.
	HTTPSProxy string
	// An optional set of SSL certificates to use.
	CaCerts *x509.CertPool
	// MaxErrorDepth is the maximum number of errors reported in a chain of errors.
	// This protects the SDK from an arbitrarily long chain of wrapped errors.
	//
	// An additional consideration is that arguably reporting a long chain of errors
	// is of little use when debugging production errors with Sentry. The Sentry UI
	// is not optimized for long chains either. The top-level error together with a
	// stack trace is often the most useful information.
	MaxErrorDepth int
	// Default event tags. These are overridden by tags set on a scope.
	Tags map[string]string
}

ClientOptions that configures a SDK Client.

type Context added in v0.14.0

type Context = map[string]interface{}

type CounterMetric added in v0.28.0

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

Counter Metric.

func NewCounterMetric added in v0.28.0

func NewCounterMetric(key string, unit MetricUnit, tags map[string]string, timestamp int64, value float64) CounterMetric

timestamp: A unix timestamp (full seconds elapsed since 1970-01-01 00:00 UTC).

func (*CounterMetric) Add added in v0.28.0

func (c *CounterMetric) Add(value float64)

func (CounterMetric) GetKey added in v0.28.0

func (am CounterMetric) GetKey() string

func (CounterMetric) GetTags added in v0.28.0

func (am CounterMetric) GetTags() map[string]string

func (CounterMetric) GetTimestamp added in v0.28.0

func (am CounterMetric) GetTimestamp() int64

func (CounterMetric) GetType added in v0.28.0

func (c CounterMetric) GetType() string

func (CounterMetric) GetUnit added in v0.28.0

func (am CounterMetric) GetUnit() string

func (CounterMetric) SerializeTags added in v0.28.0

func (am CounterMetric) SerializeTags() string

func (CounterMetric) SerializeValue added in v0.28.0

func (c CounterMetric) SerializeValue() string

type DebugMeta added in v0.20.0

type DebugMeta struct {
	SdkInfo *DebugMetaSdkInfo `json:"sdk_info,omitempty"`
	Images  []DebugMetaImage  `json:"images,omitempty"`
}

The DebugMeta interface is not used in Golang apps, but may be populated when proxying Events from other platforms, like iOS, Android, and the Web. (See: https://develop.sentry.dev/sdk/event-payloads/debugmeta/ ).

type DebugMetaImage added in v0.20.0

type DebugMetaImage struct {
	Type        string `json:"type,omitempty"`         // all
	ImageAddr   string `json:"image_addr,omitempty"`   // macho,elf,pe
	ImageSize   int    `json:"image_size,omitempty"`   // macho,elf,pe
	DebugID     string `json:"debug_id,omitempty"`     // macho,elf,pe,wasm,sourcemap
	DebugFile   string `json:"debug_file,omitempty"`   // macho,elf,pe,wasm
	CodeID      string `json:"code_id,omitempty"`      // macho,elf,pe,wasm
	CodeFile    string `json:"code_file,omitempty"`    // macho,elf,pe,wasm,sourcemap
	ImageVmaddr string `json:"image_vmaddr,omitempty"` // macho,elf,pe
	Arch        string `json:"arch,omitempty"`         // macho,elf,pe
	UUID        string `json:"uuid,omitempty"`         // proguard
}

type DebugMetaSdkInfo added in v0.20.0

type DebugMetaSdkInfo struct {
	SdkName           string `json:"sdk_name,omitempty"`
	VersionMajor      int    `json:"version_major,omitempty"`
	VersionMinor      int    `json:"version_minor,omitempty"`
	VersionPatchlevel int    `json:"version_patchlevel,omitempty"`
}

type DistributionMetric added in v0.28.0

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

Distribution Metric.

func NewDistributionMetric added in v0.28.0

func NewDistributionMetric(key string, unit MetricUnit, tags map[string]string, timestamp int64, value float64) DistributionMetric

timestamp: A unix timestamp (full seconds elapsed since 1970-01-01 00:00 UTC).

func (*DistributionMetric) Add added in v0.28.0

func (d *DistributionMetric) Add(value float64)

func (DistributionMetric) GetKey added in v0.28.0

func (am DistributionMetric) GetKey() string

func (DistributionMetric) GetTags added in v0.28.0

func (am DistributionMetric) GetTags() map[string]string

func (DistributionMetric) GetTimestamp added in v0.28.0

func (am DistributionMetric) GetTimestamp() int64

func (DistributionMetric) GetType added in v0.28.0

func (d DistributionMetric) GetType() string

func (DistributionMetric) GetUnit added in v0.28.0

func (am DistributionMetric) GetUnit() string

func (DistributionMetric) SerializeTags added in v0.28.0

func (am DistributionMetric) SerializeTags() string

func (DistributionMetric) SerializeValue added in v0.28.0

func (d DistributionMetric) SerializeValue() string

type Dsn

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

Dsn is used as the remote address source to client transport.

func NewDsn

func NewDsn(rawURL string) (*Dsn, error)

NewDsn creates a Dsn by parsing rawURL. Most users will never call this function directly. It is provided for use in custom Transport implementations.

func (Dsn) GetAPIURL added in v0.21.0

func (dsn Dsn) GetAPIURL() *url.URL

GetAPIURL returns the URL of the envelope endpoint of the project associated with the DSN.

func (Dsn) GetHost added in v0.18.0

func (dsn Dsn) GetHost() string

Get the host of the DSN.

func (Dsn) GetPath added in v0.18.0

func (dsn Dsn) GetPath() string

Get the path of the DSN.

func (Dsn) GetPort added in v0.18.0

func (dsn Dsn) GetPort() int

Get the port of the DSN.

func (Dsn) GetProjectID added in v0.18.0

func (dsn Dsn) GetProjectID() string

Get the project ID of the DSN.

func (Dsn) GetPublicKey added in v0.18.0

func (dsn Dsn) GetPublicKey() string

Get the public key of the DSN.

func (Dsn) GetScheme added in v0.18.0

func (dsn Dsn) GetScheme() string

Get the scheme of the DSN.

func (Dsn) GetSecretKey added in v0.18.0

func (dsn Dsn) GetSecretKey() string

Get the secret key of the DSN.

func (Dsn) MarshalJSON

func (dsn Dsn) MarshalJSON() ([]byte, error)

MarshalJSON converts the Dsn struct to JSON.

func (Dsn) RequestHeaders deprecated

func (dsn Dsn) RequestHeaders() map[string]string

RequestHeaders returns all the necessary headers that have to be used in the transport when seinding events to the /store endpoint.

Deprecated: This method shall only be used if you want to implement your own transport that sends events to the /store endpoint. If you're using the transport provided by the SDK, all necessary headers to authenticate against the /envelope endpoint are added automatically.

func (Dsn) String

func (dsn Dsn) String() string

String formats Dsn struct into a valid string url.

func (*Dsn) UnmarshalJSON

func (dsn *Dsn) UnmarshalJSON(data []byte) error

UnmarshalJSON converts JSON data to the Dsn struct.

type DsnParseError

type DsnParseError struct {
	Message string
}

DsnParseError represents an error that occurs if a Sentry DSN cannot be parsed.

func (DsnParseError) Error

func (e DsnParseError) Error() string

type DynamicSamplingContext added in v0.16.0

type DynamicSamplingContext struct {
	Entries map[string]string
	Frozen  bool
}

DynamicSamplingContext holds information about the current event that can be used to make dynamic sampling decisions.

func DynamicSamplingContextFromHeader added in v0.16.0

func DynamicSamplingContextFromHeader(header []byte) (DynamicSamplingContext, error)

func DynamicSamplingContextFromScope added in v0.29.0

func DynamicSamplingContextFromScope(scope *Scope, client *Client) DynamicSamplingContext

Constructs a new DynamicSamplingContext using a scope and client. Accessing fields on the scope are not thread safe, and this function should only be called within scope methods.

func DynamicSamplingContextFromTransaction added in v0.16.0

func DynamicSamplingContextFromTransaction(span *Span) DynamicSamplingContext

func (DynamicSamplingContext) HasEntries added in v0.16.0

func (d DynamicSamplingContext) HasEntries() bool

func (DynamicSamplingContext) IsFrozen added in v0.16.0

func (d DynamicSamplingContext) IsFrozen() bool

func (DynamicSamplingContext) String added in v0.16.0

func (d DynamicSamplingContext) String() string

type Event

type Event struct {
	Breadcrumbs []*Breadcrumb          `json:"breadcrumbs,omitempty"`
	Contexts    map[string]Context     `json:"contexts,omitempty"`
	Dist        string                 `json:"dist,omitempty"`
	Environment string                 `json:"environment,omitempty"`
	EventID     EventID                `json:"event_id,omitempty"`
	Extra       map[string]interface{} `json:"extra,omitempty"`
	Fingerprint []string               `json:"fingerprint,omitempty"`
	Level       Level                  `json:"level,omitempty"`
	Message     string                 `json:"message,omitempty"`
	Platform    string                 `json:"platform,omitempty"`
	Release     string                 `json:"release,omitempty"`
	Sdk         SdkInfo                `json:"sdk,omitempty"`
	ServerName  string                 `json:"server_name,omitempty"`
	Threads     []Thread               `json:"threads,omitempty"`
	Tags        map[string]string      `json:"tags,omitempty"`
	Timestamp   time.Time              `json:"timestamp"`
	Transaction string                 `json:"transaction,omitempty"`
	User        User                   `json:"user,omitempty"`
	Logger      string                 `json:"logger,omitempty"`
	Modules     map[string]string      `json:"modules,omitempty"`
	Request     *Request               `json:"request,omitempty"`
	Exception   []Exception            `json:"exception,omitempty"`
	DebugMeta   *DebugMeta             `json:"debug_meta,omitempty"`
	Attachments []*Attachment          `json:"-"`
	Metrics     []Metric               `json:"-"`

	Type            string           `json:"type,omitempty"`
	StartTime       time.Time        `json:"start_timestamp"`
	Spans           []*Span          `json:"spans,omitempty"`
	TransactionInfo *TransactionInfo `json:"transaction_info,omitempty"`

	CheckIn       *CheckIn       `json:"check_in,omitempty"`
	MonitorConfig *MonitorConfig `json:"monitor_config,omitempty"`
	// contains filtered or unexported fields
}

Event is the fundamental data structure that is sent to Sentry.

func NewEvent

func NewEvent() *Event

NewEvent creates a new Event.

func (*Event) MarshalJSON added in v0.6.0

func (e *Event) MarshalJSON() ([]byte, error)

MarshalJSON converts the Event struct to JSON.

func (*Event) SetException added in v0.21.0

func (e *Event) SetException(exception error, maxErrorDepth int)

SetException appends the unwrapped errors to the event's exception list.

maxErrorDepth is the maximum depth of the error chain we will look into while unwrapping the errors. If maxErrorDepth is -1, we will unwrap all errors in the chain.

type EventHint

type EventHint struct {
	Data               interface{}
	EventID            string
	OriginalException  error
	RecoveredException interface{}
	Context            context.Context
	Request            *http.Request
	Response           *http.Response
}

EventHint contains information that can be associated with an Event.

type EventID

type EventID string

EventID is a hexadecimal string representing a unique uuid4 for an Event. An EventID must be 32 characters long, lowercase and not have any dashes.

func CaptureCheckIn added in v0.23.0

func CaptureCheckIn(checkIn *CheckIn, monitorConfig *MonitorConfig) *EventID

CaptureCheckIn captures a (cron) monitor check-in.

func CaptureEvent

func CaptureEvent(event *Event) *EventID

CaptureEvent captures an event on the currently active client if any.

The event must already be assembled. Typically code would instead use the utility methods like CaptureException. The return value is the event ID. In case Sentry is disabled or event was dropped, the return value will be nil.

func CaptureException

func CaptureException(exception error) *EventID

CaptureException captures an error.

func CaptureMessage

func CaptureMessage(message string) *EventID

CaptureMessage captures an arbitrary message.

func LastEventID

func LastEventID() EventID

LastEventID returns an ID of last captured event.

func Recover

func Recover() *EventID

Recover captures a panic.

func RecoverWithContext

func RecoverWithContext(ctx context.Context) *EventID

RecoverWithContext captures a panic and passes relevant context object.

type EventModifier

type EventModifier interface {
	ApplyToEvent(event *Event, hint *EventHint, client *Client) *Event
}

EventModifier is the interface that wraps the ApplyToEvent method.

ApplyToEvent changes an event based on external data and/or an event hint.

type EventProcessor

type EventProcessor func(event *Event, hint *EventHint) *Event

EventProcessor is a function that processes an event. Event processors are used to change an event before it is sent to Sentry.

type Exception

type Exception struct {
	Type       string      `json:"type,omitempty"`  // used as the main issue title
	Value      string      `json:"value,omitempty"` // used as the main issue subtitle
	Module     string      `json:"module,omitempty"`
	ThreadID   uint64      `json:"thread_id,omitempty"`
	Stacktrace *Stacktrace `json:"stacktrace,omitempty"`
	Mechanism  *Mechanism  `json:"mechanism,omitempty"`
}

Exception specifies an error that occurred.

type Frame

type Frame struct {
	Function string `json:"function,omitempty"`
	Symbol   string `json:"symbol,omitempty"`
	// Module is, despite the name, the Sentry protocol equivalent of a Go
	// package's import path.
	Module      string                 `json:"module,omitempty"`
	Filename    string                 `json:"filename,omitempty"`
	AbsPath     string                 `json:"abs_path,omitempty"`
	Lineno      int                    `json:"lineno,omitempty"`
	Colno       int                    `json:"colno,omitempty"`
	PreContext  []string               `json:"pre_context,omitempty"`
	ContextLine string                 `json:"context_line,omitempty"`
	PostContext []string               `json:"post_context,omitempty"`
	InApp       bool                   `json:"in_app"`
	Vars        map[string]interface{} `json:"vars,omitempty"`
	// Package and the below are not used for Go stack trace frames.  In
	// other platforms it refers to a container where the Module can be
	// found.  For example, a Java JAR, a .NET Assembly, or a native
	// dynamic library.  They exists for completeness, allowing the
	// construction and reporting of custom event payloads.
	Package         string `json:"package,omitempty"`
	InstructionAddr string `json:"instruction_addr,omitempty"`
	AddrMode        string `json:"addr_mode,omitempty"`
	SymbolAddr      string `json:"symbol_addr,omitempty"`
	ImageAddr       string `json:"image_addr,omitempty"`
	Platform        string `json:"platform,omitempty"`
	StackStart      bool   `json:"stack_start,omitempty"`
}

Frame represents a function call and it's metadata. Frames are associated with a Stacktrace.

func NewFrame

func NewFrame(f runtime.Frame) Frame

NewFrame assembles a stacktrace frame out of runtime.Frame.

type GaugeMetric added in v0.28.0

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

Gauge Metric.

func NewGaugeMetric added in v0.28.0

func NewGaugeMetric(key string, unit MetricUnit, tags map[string]string, timestamp int64, value float64) GaugeMetric

timestamp: A unix timestamp (full seconds elapsed since 1970-01-01 00:00 UTC).

func (*GaugeMetric) Add added in v0.28.0

func (g *GaugeMetric) Add(value float64)

func (GaugeMetric) GetKey added in v0.28.0

func (am GaugeMetric) GetKey() string

func (GaugeMetric) GetTags added in v0.28.0

func (am GaugeMetric) GetTags() map[string]string

func (GaugeMetric) GetTimestamp added in v0.28.0

func (am GaugeMetric) GetTimestamp() int64

func (GaugeMetric) GetType added in v0.28.0

func (g GaugeMetric) GetType() string

func (GaugeMetric) GetUnit added in v0.28.0

func (am GaugeMetric) GetUnit() string

func (GaugeMetric) SerializeTags added in v0.28.0

func (am GaugeMetric) SerializeTags() string

func (GaugeMetric) SerializeValue added in v0.28.0

func (g GaugeMetric) SerializeValue() string

type HTTPSyncTransport

type HTTPSyncTransport struct {

	// HTTP Client request timeout. Defaults to 30 seconds.
	Timeout time.Duration
	// contains filtered or unexported fields
}

HTTPSyncTransport is a blocking implementation of Transport.

Clients using this transport will send requests to Sentry sequentially and block until a response is returned.

The blocking behavior is useful in a limited set of use cases. For example, use it when deploying code to a Function as a Service ("Serverless") platform, where any work happening in a background goroutine is not guaranteed to execute.

For most cases, prefer HTTPTransport.

func NewHTTPSyncTransport

func NewHTTPSyncTransport() *HTTPSyncTransport

NewHTTPSyncTransport returns a new pre-configured instance of HTTPSyncTransport.

func (*HTTPSyncTransport) Configure

func (t *HTTPSyncTransport) Configure(options ClientOptions)

Configure is called by the Client itself, providing it it's own ClientOptions.

func (*HTTPSyncTransport) Flush

func (t *HTTPSyncTransport) Flush(_ time.Duration) bool

Flush is a no-op for HTTPSyncTransport. It always returns true immediately.

func (*HTTPSyncTransport) SendEvent

func (t *HTTPSyncTransport) SendEvent(event *Event)

SendEvent assembles a new packet out of Event and sends it to the remote server.

func (*HTTPSyncTransport) SendEventWithContext added in v0.28.0

func (t *HTTPSyncTransport) SendEventWithContext(ctx context.Context, event *Event)

SendEventWithContext assembles a new packet out of Event and sends it to the remote server.

type HTTPTransport

type HTTPTransport struct {

	// Size of the transport buffer. Defaults to 30.
	BufferSize int
	// HTTP Client request timeout. Defaults to 30 seconds.
	Timeout time.Duration
	// contains filtered or unexported fields
}

HTTPTransport is the default, non-blocking, implementation of Transport.

Clients using this transport will enqueue requests in a buffer and return to the caller before any network communication has happened. Requests are sent to Sentry sequentially from a background goroutine.

func NewHTTPTransport

func NewHTTPTransport() *HTTPTransport

NewHTTPTransport returns a new pre-configured instance of HTTPTransport.

func (*HTTPTransport) Configure

func (t *HTTPTransport) Configure(options ClientOptions)

Configure is called by the Client itself, providing it it's own ClientOptions.

func (*HTTPTransport) Flush

func (t *HTTPTransport) Flush(timeout time.Duration) bool

Flush waits until any buffered events are sent to the Sentry server, blocking for at most the given timeout. It returns false if the timeout was reached. In that case, some events may not have been sent.

Flush should be called before terminating the program to avoid unintentionally dropping events.

Do not call Flush indiscriminately after every call to SendEvent. Instead, to have the SDK send events over the network synchronously, configure it to use the HTTPSyncTransport in the call to Init.

func (*HTTPTransport) SendEvent

func (t *HTTPTransport) SendEvent(event *Event)

SendEvent assembles a new packet out of Event and sends it to the remote server.

func (*HTTPTransport) SendEventWithContext added in v0.28.0

func (t *HTTPTransport) SendEventWithContext(ctx context.Context, event *Event)

SendEventWithContext assembles a new packet out of Event and sends it to the remote server.

type Hub

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

Hub is the central object that manages scopes and clients.

This can be used to capture events and manage the scope. The default hub that is available automatically.

In most situations developers do not need to interface the hub. Instead toplevel convenience functions are exposed that will automatically dispatch to global (CurrentHub) hub. In some situations this might not be possible in which case it might become necessary to manually work with the hub. This is for instance the case when working with async code.

func CurrentHub

func CurrentHub() *Hub

CurrentHub returns an instance of previously initialized Hub stored in the global namespace.

func GetHubFromContext

func GetHubFromContext(ctx context.Context) *Hub

GetHubFromContext tries to retrieve Hub instance from the given Context struct or return nil if one is not found.

func NewHub

func NewHub(client *Client, scope *Scope) *Hub

NewHub returns an instance of a Hub with provided Client and Scope bound.

func (*Hub) AddBreadcrumb

func (hub *Hub) AddBreadcrumb(breadcrumb *Breadcrumb, hint *BreadcrumbHint)

AddBreadcrumb records a new breadcrumb.

The total number of breadcrumbs that can be recorded are limited by the configuration on the client.

func (*Hub) BindClient

func (hub *Hub) BindClient(client *Client)

BindClient binds a new Client for the current Hub.

func (*Hub) CaptureCheckIn added in v0.23.0

func (hub *Hub) CaptureCheckIn(checkIn *CheckIn, monitorConfig *MonitorConfig) *EventID

CaptureCheckIn calls the method of the same name on currently bound Client instance passing it a top-level Scope. Returns CheckInID if the check-in was captured successfully, or nil otherwise.

func (*Hub) CaptureEvent

func (hub *Hub) CaptureEvent(event *Event) *EventID

CaptureEvent calls the method of a same name on currently bound Client instance passing it a top-level Scope. Returns EventID if successfully, or nil if there's no Scope or Client available.

func (*Hub) CaptureException

func (hub *Hub) CaptureException(exception error) *EventID

CaptureException calls the method of a same name on currently bound Client instance passing it a top-level Scope. Returns EventID if successfully, or nil if there's no Scope or Client available.

func (*Hub) CaptureMessage

func (hub *Hub) CaptureMessage(message string) *EventID

CaptureMessage calls the method of a same name on currently bound Client instance passing it a top-level Scope. Returns EventID if successfully, or nil if there's no Scope or Client available.

func (*Hub) Client

func (hub *Hub) Client() *Client

Client returns top-level Client of the current Hub or nil if no Client is bound.

func (*Hub) Clone

func (hub *Hub) Clone() *Hub

Clone returns a copy of the current Hub with top-most scope and client copied over.

func (*Hub) ConfigureScope

func (hub *Hub) ConfigureScope(f func(scope *Scope))

ConfigureScope runs f in the current scope.

It is useful to set data that applies to all events that share the current scope.

Modifying the scope affects all references to the current scope.

See also WithScope for making isolated temporary changes.

func (*Hub) Flush

func (hub *Hub) Flush(timeout time.Duration) bool

Flush waits until the underlying Transport sends any buffered events to the Sentry server, blocking for at most the given timeout. It returns false if the timeout was reached. In that case, some events may not have been sent.

Flush should be called before terminating the program to avoid unintentionally dropping events.

Do not call Flush indiscriminately after every call to CaptureEvent, CaptureException or CaptureMessage. Instead, to have the SDK send events over the network synchronously, configure it to use the HTTPSyncTransport in the call to Init.

func (*Hub) GetBaggage added in v0.29.0

func (hub *Hub) GetBaggage() string

GetBaggage returns the current Sentry baggage string, to be used as a HTTP header value or HTML meta tag value. This function is context aware, as in it either returns the baggage based on the current span or the scope's propagation context.

func (*Hub) GetTraceparent added in v0.29.0

func (hub *Hub) GetTraceparent() string

GetTraceparent returns the current Sentry traceparent string, to be used as a HTTP header value or HTML meta tag value. This function is context aware, as in it either returns the traceparent based on the current span, or the scope's propagation context.

func (*Hub) LastEventID

func (hub *Hub) LastEventID() EventID

LastEventID returns the ID of the last event (error or message) captured through the hub and sent to the underlying transport.

Transactions and events dropped by sampling or event processors do not change the last event ID.

LastEventID is a convenience method to cover use cases in which errors are captured indirectly and the ID is needed. For example, it can be used as part of an HTTP middleware to log the ID of the last error, if any.

For more flexibility, consider instead using the ClientOptions.BeforeSend function or event processors.

func (*Hub) PopScope

func (hub *Hub) PopScope()

PopScope drops the most recent scope.

Calls to PopScope must be coordinated with PushScope. For most cases, using WithScope should be more convenient.

Calls to PopScope that do not match previous calls to PushScope are silently ignored.

func (*Hub) PushScope

func (hub *Hub) PushScope() *Scope

PushScope pushes a new scope for the current Hub and reuses previously bound Client.

func (*Hub) Recover

func (hub *Hub) Recover(err interface{}) *EventID

Recover calls the method of a same name on currently bound Client instance passing it a top-level Scope. Returns EventID if successfully, or nil if there's no Scope or Client available.

func (*Hub) RecoverWithContext

func (hub *Hub) RecoverWithContext(ctx context.Context, err interface{}) *EventID

RecoverWithContext calls the method of a same name on currently bound Client instance passing it a top-level Scope. Returns EventID if successfully, or nil if there's no Scope or Client available.

func (*Hub) Scope

func (hub *Hub) Scope() *Scope

Scope returns top-level Scope of the current Hub or nil if no Scope is bound.

func (*Hub) WithScope

func (hub *Hub) WithScope(f func(scope *Scope))

WithScope runs f in an isolated temporary scope.

It is useful when extra data should be sent with a single capture call, for instance a different level or tags.

The scope passed to f starts as a clone of the current scope and can be freely modified without affecting the current scope.

It is a shorthand for PushScope followed by PopScope.

type Integration

type Integration interface {
	Name() string
	SetupOnce(client *Client)
}

Integration allows for registering a functions that modify or discard captured events.

type Level

type Level string

Level marks the severity of the event.

const (
	LevelDebug   Level = "debug"
	LevelInfo    Level = "info"
	LevelWarning Level = "warning"
	LevelError   Level = "error"
	LevelFatal   Level = "fatal"
)

Describes the severity of the event.

type Mechanism added in v0.19.0

type Mechanism struct {
	Type             string         `json:"type,omitempty"`
	Description      string         `json:"description,omitempty"`
	HelpLink         string         `json:"help_link,omitempty"`
	Source           string         `json:"source,omitempty"`
	Handled          *bool          `json:"handled,omitempty"`
	ParentID         *int           `json:"parent_id,omitempty"`
	ExceptionID      int            `json:"exception_id"`
	IsExceptionGroup bool           `json:"is_exception_group,omitempty"`
	Data             map[string]any `json:"data,omitempty"`
}

Mechanism is the mechanism by which an exception was generated and handled.

func (*Mechanism) SetUnhandled added in v0.19.0

func (m *Mechanism) SetUnhandled()

SetUnhandled indicates that the exception is an unhandled exception, i.e. from a panic.

type Metric added in v0.28.0

type Metric interface {
	GetType() string
	GetTags() map[string]string
	GetKey() string
	GetUnit() string
	GetTimestamp() int64
	SerializeValue() string
	SerializeTags() string
}

type MetricUnit added in v0.28.0

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

func Bit added in v0.28.0

func Bit() MetricUnit

func Byte added in v0.28.0

func Byte() MetricUnit

func CustomUnit added in v0.28.0

func CustomUnit(unit string) MetricUnit

func Day added in v0.28.0

func Day() MetricUnit

func ExaByte added in v0.28.0

func ExaByte() MetricUnit

func ExbiByte added in v0.28.0

func ExbiByte() MetricUnit

func GibiByte added in v0.28.0

func GibiByte() MetricUnit

func GigaByte added in v0.28.0

func GigaByte() MetricUnit

func Hour added in v0.28.0

func Hour() MetricUnit

func KibiByte added in v0.28.0

func KibiByte() MetricUnit

func KiloByte added in v0.28.0

func KiloByte() MetricUnit

func MebiByte added in v0.28.0

func MebiByte() MetricUnit

func MegaByte added in v0.28.0

func MegaByte() MetricUnit

func MicroSecond added in v0.28.0

func MicroSecond() MetricUnit

func MilliSecond added in v0.28.0

func MilliSecond() MetricUnit

func Minute added in v0.28.0

func Minute() MetricUnit

func NanoSecond added in v0.28.0

func NanoSecond() MetricUnit

func PebiByte added in v0.28.0

func PebiByte() MetricUnit

func Percent added in v0.28.0

func Percent() MetricUnit

func PetaByte added in v0.28.0

func PetaByte() MetricUnit

func Ratio added in v0.28.0

func Ratio() MetricUnit

func Second added in v0.28.0

func Second() MetricUnit

func TebiByte added in v0.28.0

func TebiByte() MetricUnit

func TeraByte added in v0.28.0

func TeraByte() MetricUnit

func Week added in v0.28.0

func Week() MetricUnit

type MonitorConfig added in v0.23.0

type MonitorConfig struct {
	Schedule MonitorSchedule `json:"schedule,omitempty"`
	// The allowed margin of minutes after the expected check-in time that
	// the monitor will not be considered missed for.
	CheckInMargin int64 `json:"checkin_margin,omitempty"`
	// The allowed duration in minutes that the monitor may be `in_progress`
	// for before being considered failed due to timeout.
	MaxRuntime int64 `json:"max_runtime,omitempty"`
	// A tz database string representing the timezone which the monitor's execution schedule is in.
	// See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
	Timezone string `json:"timezone,omitempty"`
	// The number of consecutive failed check-ins it takes before an issue is created.
	FailureIssueThreshold int64 `json:"failure_issue_threshold,omitempty"`
	// The number of consecutive OK check-ins it takes before an issue is resolved.
	RecoveryThreshold int64 `json:"recovery_threshold,omitempty"`
}

type MonitorSchedule added in v0.23.0

type MonitorSchedule interface {
	// contains filtered or unexported methods
}

func CrontabSchedule added in v0.23.0

func CrontabSchedule(scheduleString string) MonitorSchedule

CrontabSchedule defines the MonitorSchedule with a cron format. Example: "8 * * * *".

func IntervalSchedule added in v0.23.0

func IntervalSchedule(value int64, unit MonitorScheduleUnit) MonitorSchedule

IntervalSchedule defines the MonitorSchedule with an interval format.

Example:

IntervalSchedule(1, sentry.MonitorScheduleUnitDay)

type MonitorScheduleUnit added in v0.23.0

type MonitorScheduleUnit string
const (
	MonitorScheduleUnitMinute MonitorScheduleUnit = "minute"
	MonitorScheduleUnitHour   MonitorScheduleUnit = "hour"
	MonitorScheduleUnitDay    MonitorScheduleUnit = "day"
	MonitorScheduleUnitWeek   MonitorScheduleUnit = "week"
	MonitorScheduleUnitMonth  MonitorScheduleUnit = "month"
	MonitorScheduleUnitYear   MonitorScheduleUnit = "year"
)

type NumberOrString added in v0.28.0

type NumberOrString interface {
	int | string
}

type Ordered added in v0.28.0

type Ordered interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr | ~float32 | ~float64 | ~string
}

type PropagationContext added in v0.29.0

type PropagationContext struct {
	TraceID                TraceID                `json:"trace_id"`
	SpanID                 SpanID                 `json:"span_id"`
	ParentSpanID           SpanID                 `json:"parent_span_id"`
	DynamicSamplingContext DynamicSamplingContext `json:"-"`
}

func NewPropagationContext added in v0.29.0

func NewPropagationContext() PropagationContext

func PropagationContextFromHeaders added in v0.29.0

func PropagationContextFromHeaders(trace, baggage string) (PropagationContext, error)

func (PropagationContext) Map added in v0.29.0

func (p PropagationContext) Map() map[string]interface{}

func (PropagationContext) MarshalJSON added in v0.29.0

func (p PropagationContext) MarshalJSON() ([]byte, error)

type Request

type Request struct {
	URL         string            `json:"url,omitempty"`
	Method      string            `json:"method,omitempty"`
	Data        string            `json:"data,omitempty"`
	QueryString string            `json:"query_string,omitempty"`
	Cookies     string            `json:"cookies,omitempty"`
	Headers     map[string]string `json:"headers,omitempty"`
	Env         map[string]string `json:"env,omitempty"`
}

Request contains information on a HTTP request related to the event.

func NewRequest added in v0.6.0

func NewRequest(r *http.Request) *Request

NewRequest returns a new Sentry Request from the given http.Request.

NewRequest avoids operations that depend on network access. In particular, it does not read r.Body.

type SDKMetaData added in v0.16.0

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

SDKMetaData is a struct to stash data which is needed at some point in the SDK's event processing pipeline but which shouldn't get send to Sentry.

type Sampled added in v0.9.0

type Sampled int8

Sampled signifies a sampling decision.

const (
	SampledFalse     Sampled = -1
	SampledUndefined Sampled = 0
	SampledTrue      Sampled = 1
)

The possible trace sampling decisions are: SampledFalse, SampledUndefined (default) and SampledTrue.

func (Sampled) Bool added in v0.9.0

func (s Sampled) Bool() bool

Bool returns true if the sample decision is SampledTrue, false otherwise.

func (Sampled) String added in v0.9.0

func (s Sampled) String() string

type SamplingContext added in v0.9.0

type SamplingContext struct {
	Span   *Span // The current span, always non-nil.
	Parent *Span // The parent span, may be nil.
}

A SamplingContext is passed to a TracesSampler to determine a sampling decision.

TODO(tracing): possibly expand SamplingContext to include custom / user-provided data.

type Scope

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

Scope holds contextual data for the current scope.

The scope is an object that can cloned efficiently and stores data that is locally relevant to an event. For instance the scope will hold recorded breadcrumbs and similar information.

The scope can be interacted with in two ways. First, the scope is routinely updated with information by functions such as AddBreadcrumb which will modify the current scope. Second, the current scope can be configured through the ConfigureScope function or Hub method of the same name.

The scope is meant to be modified but not inspected directly. When preparing an event for reporting, the current client adds information from the current scope into the event.

func NewScope

func NewScope() *Scope

NewScope creates a new Scope.

func (*Scope) AddAttachment added in v0.23.0

func (scope *Scope) AddAttachment(attachment *Attachment)

AddAttachment adds new attachment to the current scope.

func (*Scope) AddBreadcrumb

func (scope *Scope) AddBreadcrumb(breadcrumb *Breadcrumb, limit int)

AddBreadcrumb adds new breadcrumb to the current scope and optionally throws the old one if limit is reached.

func (*Scope) AddEventProcessor

func (scope *Scope) AddEventProcessor(processor EventProcessor)

AddEventProcessor adds an event processor to the current scope.

func (*Scope) ApplyToEvent

func (scope *Scope) ApplyToEvent(event *Event, hint *EventHint, client *Client) *Event

ApplyToEvent takes the data from the current scope and attaches it to the event.

func (*Scope) Clear

func (scope *Scope) Clear()

Clear removes the data from the current scope. Not safe for concurrent use.

func (*Scope) ClearAttachments added in v0.23.0

func (scope *Scope) ClearAttachments()

ClearAttachments clears all attachments from the current scope.

func (*Scope) ClearBreadcrumbs

func (scope *Scope) ClearBreadcrumbs()

ClearBreadcrumbs clears all breadcrumbs from the current scope.

func (*Scope) Clone

func (scope *Scope) Clone() *Scope

Clone returns a copy of the current scope with all data copied over.

func (*Scope) RemoveContext

func (scope *Scope) RemoveContext(key string)

RemoveContext removes a context from the current scope.

func (*Scope) RemoveExtra

func (scope *Scope) RemoveExtra(key string)

RemoveExtra removes a extra from the current scope.

func (*Scope) RemoveTag

func (scope *Scope) RemoveTag(key string)

RemoveTag removes a tag from the current scope.

func (*Scope) SetContext

func (scope *Scope) SetContext(key string, value Context)

SetContext adds a context to the current scope.

func (*Scope) SetContexts

func (scope *Scope) SetContexts(contexts map[string]Context)

SetContexts assigns multiple contexts to the current scope.

func (*Scope) SetExtra

func (scope *Scope) SetExtra(key string, value interface{})

SetExtra adds an extra to the current scope.

func (*Scope) SetExtras

func (scope *Scope) SetExtras(extra map[string]interface{})

SetExtras assigns multiple extras to the current scope.

func (*Scope) SetFingerprint

func (scope *Scope) SetFingerprint(fingerprint []string)

SetFingerprint sets new fingerprint for the current scope.

func (*Scope) SetLevel

func (scope *Scope) SetLevel(level Level)

SetLevel sets new level for the current scope.

func (*Scope) SetPropagationContext added in v0.29.0

func (scope *Scope) SetPropagationContext(propagationContext PropagationContext)

SetPropagationContext sets the propagation context for the current scope.

func (*Scope) SetRequest

func (scope *Scope) SetRequest(r *http.Request)

SetRequest sets the request for the current scope.

func (*Scope) SetRequestBody added in v0.6.0

func (scope *Scope) SetRequestBody(b []byte)

SetRequestBody sets the request body for the current scope.

This method should only be called when the body bytes are already available in memory. Typically, the request body is buffered lazily from the Request.Body from SetRequest.

func (*Scope) SetSpan added in v0.29.0

func (scope *Scope) SetSpan(span *Span)

SetSpan sets a span for the current scope.

func (*Scope) SetTag

func (scope *Scope) SetTag(key, value string)

SetTag adds a tag to the current scope.

func (*Scope) SetTags

func (scope *Scope) SetTags(tags map[string]string)

SetTags assigns multiple tags to the current scope.

func (*Scope) SetUser

func (scope *Scope) SetUser(user User)

SetUser sets the user for the current scope.

type SdkInfo

type SdkInfo struct {
	Name         string       `json:"name,omitempty"`
	Version      string       `json:"version,omitempty"`
	Integrations []string     `json:"integrations,omitempty"`
	Packages     []SdkPackage `json:"packages,omitempty"`
}

SdkInfo contains all metadata about about the SDK being used.

type SdkPackage

type SdkPackage struct {
	Name    string `json:"name,omitempty"`
	Version string `json:"version,omitempty"`
}

SdkPackage describes a package that was installed.

type SetMetric added in v0.28.0

type SetMetric[T NumberOrString] struct {
	// contains filtered or unexported fields
}

Set Metric.

func NewSetMetric added in v0.28.0

func NewSetMetric[T NumberOrString](key string, unit MetricUnit, tags map[string]string, timestamp int64, value T) SetMetric[T]

timestamp: A unix timestamp (full seconds elapsed since 1970-01-01 00:00 UTC).

func (*SetMetric[T]) Add added in v0.28.0

func (s *SetMetric[T]) Add(value T)

func (SetMetric) GetKey added in v0.28.0

func (am SetMetric) GetKey() string

func (SetMetric) GetTags added in v0.28.0

func (am SetMetric) GetTags() map[string]string

func (SetMetric) GetTimestamp added in v0.28.0

func (am SetMetric) GetTimestamp() int64

func (SetMetric[T]) GetType added in v0.28.0

func (s SetMetric[T]) GetType() string

func (SetMetric) GetUnit added in v0.28.0

func (am SetMetric) GetUnit() string

func (SetMetric) SerializeTags added in v0.28.0

func (am SetMetric) SerializeTags() string

func (SetMetric[T]) SerializeValue added in v0.28.0

func (s SetMetric[T]) SerializeValue() string

type Span added in v0.7.0

type Span struct {
	TraceID      TraceID                `json:"trace_id"`
	SpanID       SpanID                 `json:"span_id"`
	ParentSpanID SpanID                 `json:"parent_span_id"`
	Name         string                 `json:"name,omitempty"`
	Op           string                 `json:"op,omitempty"`
	Description  string                 `json:"description,omitempty"`
	Status       SpanStatus             `json:"status,omitempty"`
	Tags         map[string]string      `json:"tags,omitempty"`
	StartTime    time.Time              `json:"start_timestamp"`
	EndTime      time.Time              `json:"timestamp"`
	Data         map[string]interface{} `json:"data,omitempty"`
	Sampled      Sampled                `json:"-"`
	Source       TransactionSource      `json:"-"`
	Origin       SpanOrigin             `json:"origin,omitempty"`
	// contains filtered or unexported fields
}

A Span is the building block of a Sentry transaction. Spans build up a tree structure of timed operations. The span tree makes up a transaction event that is sent to Sentry when the root span is finished.

Spans must be started with either StartSpan or Span.StartChild.

func SpanFromContext added in v0.23.0

func SpanFromContext(ctx context.Context) *Span

SpanFromContext returns the last span stored in the context, or nil if no span is set on the context.

func StartSpan added in v0.9.0

func StartSpan(ctx context.Context, operation string, options ...SpanOption) *Span

StartSpan starts a new span to describe an operation. The new span will be a child of the last span stored in ctx, if any.

One or more options can be used to modify the span properties. Typically one option as a function literal is enough. Combining multiple options can be useful to define and reuse specific properties with named functions.

Caller should call the Finish method on the span to mark its end. Finishing a root span sends the span and all of its children, recursively, as a transaction to Sentry.

func StartTransaction added in v0.15.0

func StartTransaction(ctx context.Context, name string, options ...SpanOption) *Span

StartTransaction will create a transaction (root span) if there's no existing transaction in the context otherwise, it will return the existing transaction.

func TransactionFromContext added in v0.9.0

func TransactionFromContext(ctx context.Context) *Span

TransactionFromContext returns the root span of the current transaction. It returns nil if no transaction is tracked in the context.

func (*Span) Context added in v0.9.0

func (s *Span) Context() context.Context

Context returns the context containing the span.

func (*Span) Finish added in v0.9.0

func (s *Span) Finish()

Finish sets the span's end time, unless already set. If the span is the root of a span tree, Finish sends the span tree to Sentry as a transaction.

The logic is executed at most once per span, so that (incorrectly) calling it twice never double sends to Sentry.

func (*Span) GetTransaction added in v0.18.0

func (s *Span) GetTransaction() *Span

GetTransaction returns the transaction that contains this span.

For transaction spans it returns itself. For spans that were created manually the method returns "nil".

func (*Span) IsTransaction added in v0.18.0

func (s *Span) IsTransaction() bool

IsTransaction checks if the given span is a transaction.

func (*Span) MarshalJSON added in v0.9.0

func (s *Span) MarshalJSON() ([]byte, error)

func (*Span) SetContext added in v0.20.0

func (s *Span) SetContext(key string, value Context)

SetContext sets a context on the span. It is recommended to use SetContext instead of accessing the contexts map directly as SetContext takes care of initializing the map when necessary.

func (*Span) SetData added in v0.18.0

func (s *Span) SetData(name string, value interface{})

SetData sets a data on the span. It is recommended to use SetData instead of accessing the data map directly as SetData takes care of initializing the map when necessary.

func (*Span) SetDynamicSamplingContext added in v0.18.0

func (s *Span) SetDynamicSamplingContext(dsc DynamicSamplingContext)

SetDynamicSamplingContext sets the given dynamic sampling context on the current transaction.

func (*Span) SetTag added in v0.9.0

func (s *Span) SetTag(name, value string)

SetTag sets a tag on the span. It is recommended to use SetTag instead of accessing the tags map directly as SetTag takes care of initializing the map when necessary.

func (*Span) StartChild added in v0.9.0

func (s *Span) StartChild(operation string, options ...SpanOption) *Span

StartChild starts a new child span.

The call span.StartChild(operation, options...) is a shortcut for StartSpan(span.Context(), operation, options...).

func (*Span) ToBaggage added in v0.16.0

func (s *Span) ToBaggage() string

ToBaggage returns the serialized DynamicSamplingContext from a transaction. Use this function to propagate the DynamicSamplingContext to a downstream SDK, either as the value of the "baggage" HTTP header, or as an html "baggage" meta tag.

func (*Span) ToSentryTrace added in v0.9.0

func (s *Span) ToSentryTrace() string

ToSentryTrace returns the seralized TraceParentContext from a transaction/span. Use this function to propagate the TraceParentContext to a downstream SDK, either as the value of the "sentry-trace" HTTP header, or as an html "sentry-trace" meta tag.

type SpanID added in v0.9.0

type SpanID [8]byte

SpanID identifies a span.

func (SpanID) Hex added in v0.9.0

func (id SpanID) Hex() []byte

func (SpanID) MarshalText added in v0.9.0

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

func (SpanID) String added in v0.9.0

func (id SpanID) String() string

type SpanOption added in v0.9.0

type SpanOption func(s *Span)

A SpanOption is a function that can modify the properties of a span.

func ContinueFromHeaders added in v0.16.0

func ContinueFromHeaders(trace, baggage string) SpanOption

ContinueFromHeaders returns a span option that updates the span to continue an existing TraceID and propagates the Dynamic Sampling context.

func ContinueFromRequest added in v0.9.0

func ContinueFromRequest(r *http.Request) SpanOption

ContinueFromRequest returns a span option that updates the span to continue an existing trace. If it cannot detect an existing trace in the request, the span will be left unchanged.

ContinueFromRequest is an alias for:

ContinueFromHeaders(r.Header.Get(SentryTraceHeader), r.Header.Get(SentryBaggageHeader)).

func ContinueFromTrace added in v0.14.0

func ContinueFromTrace(trace string) SpanOption

ContinueFromTrace returns a span option that updates the span to continue an existing TraceID.

func ContinueTrace added in v0.29.0

func ContinueTrace(hub *Hub, traceparent, baggage string) SpanOption

Continue a trace based on traceparent and bagge values. If the SDK is configured with tracing enabled, this function returns populated SpanOption. In any other cases, it populates the propagation context on the scope.

func WithDescription added in v0.26.0

func WithDescription(description string) SpanOption

WithDescription sets the description of a span.

func WithOpName added in v0.21.0

func WithOpName(name string) SpanOption

WithOpName sets the operation name for a given span.

func WithSpanOrigin added in v0.29.0

func WithSpanOrigin(origin SpanOrigin) SpanOption

WithSpanOrigin sets the origin of the span.

func WithSpanSampled added in v0.21.0

func WithSpanSampled(sampled Sampled) SpanOption

WithSpanSampled updates the sampling flag for a given span.

func WithTransactionName added in v0.21.0

func WithTransactionName(name string) SpanOption

WithTransactionName option sets the name of the current transaction.

A span tree has a single transaction name, therefore using this option when starting a span affects the span tree as a whole, potentially overwriting a name set previously.

func WithTransactionSource added in v0.21.0

func WithTransactionSource(source TransactionSource) SpanOption

WithTransactionSource sets the source of the transaction name.

Note: if the transaction source is not a valid source (as described by the spec https://develop.sentry.dev/sdk/event-payloads/transaction/#transaction-annotations), it will be corrected to "custom" eventually, before the transaction is sent.

type SpanOrigin added in v0.29.0

type SpanOrigin string

SpanOrigin indicates what created a trace or a span. See: https://develop.sentry.dev/sdk/performance/trace-origin/

type SpanStatus added in v0.9.0

type SpanStatus uint8

SpanStatus is the status of a span.

const (
	SpanStatusUndefined SpanStatus = iota
	SpanStatusOK
	SpanStatusCanceled
	SpanStatusUnknown
	SpanStatusInvalidArgument
	SpanStatusDeadlineExceeded
	SpanStatusNotFound
	SpanStatusAlreadyExists
	SpanStatusPermissionDenied
	SpanStatusResourceExhausted
	SpanStatusFailedPrecondition
	SpanStatusAborted
	SpanStatusOutOfRange
	SpanStatusUnimplemented
	SpanStatusInternalError
	SpanStatusUnavailable
	SpanStatusDataLoss
	SpanStatusUnauthenticated
)

func HTTPtoSpanStatus added in v0.22.0

func HTTPtoSpanStatus(code int) SpanStatus

HTTPtoSpanStatus converts an HTTP status code to a SpanStatus.

func (SpanStatus) MarshalJSON added in v0.9.0

func (ss SpanStatus) MarshalJSON() ([]byte, error)

func (SpanStatus) String added in v0.9.0

func (ss SpanStatus) String() string

type Stacktrace

type Stacktrace struct {
	Frames        []Frame `json:"frames,omitempty"`
	FramesOmitted []uint  `json:"frames_omitted,omitempty"`
}

Stacktrace holds information about the frames of the stack.

func ExtractStacktrace

func ExtractStacktrace(err error) *Stacktrace

ExtractStacktrace creates a new Stacktrace based on the given error.

func NewStacktrace

func NewStacktrace() *Stacktrace

NewStacktrace creates a stacktrace using runtime.Callers.

type Thread

type Thread struct {
	ID         string      `json:"id,omitempty"`
	Name       string      `json:"name,omitempty"`
	Stacktrace *Stacktrace `json:"stacktrace,omitempty"`
	Crashed    bool        `json:"crashed,omitempty"`
	Current    bool        `json:"current,omitempty"`
}

Thread specifies threads that were running at the time of an event.

type TraceContext added in v0.7.0

type TraceContext struct {
	TraceID      TraceID    `json:"trace_id"`
	SpanID       SpanID     `json:"span_id"`
	ParentSpanID SpanID     `json:"parent_span_id"`
	Op           string     `json:"op,omitempty"`
	Description  string     `json:"description,omitempty"`
	Status       SpanStatus `json:"status,omitempty"`
}

A TraceContext carries information about an ongoing trace and is meant to be stored in Event.Contexts (as *TraceContext).

func (TraceContext) Map added in v0.14.0

func (tc TraceContext) Map() map[string]interface{}

func (*TraceContext) MarshalJSON added in v0.9.0

func (tc *TraceContext) MarshalJSON() ([]byte, error)

type TraceID added in v0.9.0

type TraceID [16]byte

TraceID identifies a trace.

func (TraceID) Hex added in v0.9.0

func (id TraceID) Hex() []byte

func (TraceID) MarshalText added in v0.9.0

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

func (TraceID) String added in v0.9.0

func (id TraceID) String() string

type TraceParentContext added in v0.18.0

type TraceParentContext struct {
	TraceID      TraceID
	ParentSpanID SpanID
	Sampled      Sampled
}

TraceParentContext describes the context of a (remote) parent span.

The context is normally extracted from a received "sentry-trace" header and used to initialize a new transaction.

Note: the name might be not the best one. It was taken mostly to stay aligned with other SDKs, and it alludes to W3C "traceparent" header (https://www.w3.org/TR/trace-context/), which serves a similar purpose to "sentry-trace". We should eventually consider making this type internal-only and give it a better name.

func ParseTraceParentContext added in v0.18.0

func ParseTraceParentContext(header []byte) (traceParentContext TraceParentContext, valid bool)

ParseTraceParentContext parses a sentry-trace header and builds a TraceParentContext from the parsed values. If the header was parsed correctly, the second returned argument ("valid") will be set to true, otherwise (e.g., empty or malformed header) it will be false.

type TracesSampler added in v0.9.0

type TracesSampler func(ctx SamplingContext) float64

The TracesSample type is an adapter to allow the use of ordinary functions as a TracesSampler.

func (TracesSampler) Sample added in v0.9.0

func (f TracesSampler) Sample(ctx SamplingContext) float64

type TransactionInfo added in v0.16.0

type TransactionInfo struct {
	Source TransactionSource `json:"source,omitempty"`
}

Contains information about how the name of the transaction was determined.

type TransactionSource added in v0.16.0

type TransactionSource string

Contains information about how the name of the transaction was determined.

const (
	SourceCustom    TransactionSource = "custom"
	SourceURL       TransactionSource = "url"
	SourceRoute     TransactionSource = "route"
	SourceView      TransactionSource = "view"
	SourceComponent TransactionSource = "component"
	SourceTask      TransactionSource = "task"
)

type Transport

type Transport interface {
	Flush(timeout time.Duration) bool
	Configure(options ClientOptions)
	SendEvent(event *Event)
}

Transport is used by the Client to deliver events to remote server.

type User

type User struct {
	ID        string            `json:"id,omitempty"`
	Email     string            `json:"email,omitempty"`
	IPAddress string            `json:"ip_address,omitempty"`
	Username  string            `json:"username,omitempty"`
	Name      string            `json:"name,omitempty"`
	Segment   string            `json:"segment,omitempty"`
	Data      map[string]string `json:"data,omitempty"`
}

User describes the user associated with an Event. If this is used, at least an ID or an IP address should be provided.

func (User) IsEmpty added in v0.15.0

func (u User) IsEmpty() bool

Directories

Path Synopsis
_examples
basic
This is an example program that makes an HTTP request and prints response headers.
This is an example program that makes an HTTP request and prints response headers.
gin
http
This is an example web server to demonstrate how to instrument error and performance monitoring with Sentry.
This is an example web server to demonstrate how to instrument error and performance monitoring with Sentry.
recover-repanic
This is an example program that demonstrates an advanced use of the Sentry SDK using Hub, Scope and EventProcessor to recover from runtime panics, report to Sentry filtering specific frames from the stack trace and then letting the program crash as usual.
This is an example program that demonstrates an advanced use of the Sentry SDK using Hub, Scope and EventProcessor to recover from runtime panics, report to Sentry filtering specific frames from the stack trace and then letting the program crash as usual.
Package sentryhttp provides Sentry integration for servers based on the net/http package.
Package sentryhttp provides Sentry integration for servers based on the net/http package.
internal
otel/baggage/internal/baggage
Package baggage provides base types and functionality to store and retrieve baggage in Go context.
Package baggage provides base types and functionality to store and retrieve baggage in Go context.
ratelimit
Package ratelimit provides tools to work with rate limits imposed by Sentry's data ingestion pipeline.
Package ratelimit provides tools to work with rate limits imposed by Sentry's data ingestion pipeline.
Package sentrylogrus provides a simple Logrus hook for Sentry.
Package sentrylogrus provides a simple Logrus hook for Sentry.
otel module
slog module
zerolog module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL