sentry

package module
v0.0.1-beta.4 Latest Latest
Warning

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

 Go to latest Published: Jun 12, 2019 License: BSD-2-Clause Imports: 26 Imported by: 2,810

README


Official Sentry SDK for Go

Migrating from Raven-go? See: https://github.com/getsentry/sentry-go/blob/master/MIGRATION.md

Want to join our Sentry's community-golang channel, get involved and help us build the most useful SDK possible?
Do not hesistate to shoot me up an email at kamil@sentry.io

Documentation

Index

Constants

View Source 
const HubContextKey = contextKey(1)

HubContextKey is a context key used to store Hub on any context.Context type

View Source 
const RequestContextKey = contextKey(2)

RequestContextKey is a context key used to store http.Request on the context passed to RecoverWithContext

View Source 
const Version = "0.0.1-beta.3"

Version Sentry-Go SDK Version

Variables

View Source 
var Logger = log.New(ioutil.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)

func ConfigureScope 

func ConfigureScope(f func(scope *Scope))

ConfigureScope invokes a function that can modify the current scope.

The function is passed a mutable reference to the `Scope` so that modifications can be performed.

func Flush 

func Flush(timeout time.Duration) bool

Flush notifies when all the buffered events have been sent by returning `true` or `false` if timeout was reached.

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 whole SDK by creating new `Client` and binding it to the current `Hub`

func PopScope 

func PopScope()

PopScope pushes a new scope.

func PushScope 

func PushScope()

PushScope pushes a new scope.

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 temporarily pushes a scope for a single call.

This function takes one argument, a callback that executes in the context of that scope.

This is useful when extra data should be send with a single capture call for instance a different level or tags

Types 

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

https://docs.sentry.io/development/sdk-dev/interfaces/breadcrumbs/ 

type BreadcrumbHint map[string]interface{}

TODO: This type could be more useful, as map of interface{} is too generic and requires a lot of type assertions in beforeBreadcrumb calls plus it could just be `map[string]interface{}` then

type Client 

type Client struct {
	Transport Transport
	// contains filtered or unexported fields
}

Client is the underlying processor that's used by the main API and `Hub` instances.

func NewClient 

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

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

func (*Client) AddEventProcessor 

func (client *Client) AddEventProcessor(processor EventProcessor)

AddEventProcessor adds an event processor to the client.

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

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

Flush notifies when all the buffered events have been sent by returning `true` or `false` if timeout was reached. It calls `Flush` method of the configured `Transport`.

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

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

type ClientOptions 

type ClientOptions struct {
	// The DSN to use. If not set the client is effectively disabled.
	Dsn string
	// In debug mode debug information is printed to stdput 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 (0.0 - 1.0, defaults to 1.0).
	SampleRate float32
	// 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
	// Before send callback.
	BeforeSend 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.
	// This is an instance of a struct implementing `Transport` interface.
	// Defaults to `httpTransport` from `transport.go`
	Transport Transport
	// The server name to be reported.
	ServerName string
	// The release to be sent with events.
	Release string
	// The dist to be sent with events.
	Dist string
	// The environment to be sent with events.
	Environment string
	// Maximum number of breadcrumbs.
	MaxBreadcrumbs int
	// An optional size of the transport buffer. Defaults to 30.
	BufferSize int
	// An optional pointer to `http.Transport` that will be used with a default HTTPTransport.
	HTTPTransport *http.Transport
	// An optional HTTP proxy to use.
	// This will default to the `http_proxy` environment variable.
	// or `https_proxy` if that one exists.
	HTTPProxy string
	// An optional HTTPS proxy to use.
	// This will default to the `HTTPS_PROXY` environment variable
	// or `http_proxy` if that one exists.
	HTTPSProxy string
	// An optionsl CaCerts to use.
	// Defaults to `gocertifi.CACerts()`.
	CaCerts *x509.CertPool
}

ClientOptions that configures a SDK Client

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 an instance od `Dsn` by parsing provided url in a `string` format. If Dsn is not set the client is effectively disabled.

func (Dsn) MarshalJSON 

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

func (Dsn) RequestHeaders 

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

RequestHeaders returns all the necessary headers that have to be used in the transport.

func (Dsn) StoreAPIURL 

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

StoreAPIURL returns assembled url to be used in the transport. It points to configures Sentry instance.

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

type DsnParseError 

type DsnParseError struct {
	Message string
}

func (DsnParseError) Error 

func (e DsnParseError) Error() string

type Event 

type Event struct {
	Breadcrumbs []*Breadcrumb          `json:"breadcrumbs,omitempty"`
	Contexts    map[string]interface{} `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   int64                  `json:"timestamp,omitempty"`
	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"`
}

https://docs.sentry.io/development/sdk-dev/attributes/

func NewEvent 

func NewEvent() *Event

type EventHint 

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

type EventID 

type EventID string

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

Recover captures a panic and passes relevant context object.

type EventModifier 

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

type EventProcessor 

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

type Exception 

type Exception struct {
	Type          string      `json:"type,omitempty"`
	Value         string      `json:"value,omitempty"`
	Module        string      `json:"module,omitempty"`
	Stacktrace    *Stacktrace `json:"stacktrace,omitempty"`
	RawStacktrace *Stacktrace `json:"raw_stacktrace,omitempty"`
}

https://docs.sentry.io/development/sdk-dev/interfaces/exception/

type Frame 

type Frame struct {
	Function    string                 `json:"function,omitempty"`
	Symbol      string                 `json:"symbol,omitempty"`
	Module      string                 `json:"module,omitempty"`
	Package     string                 `json:"package,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,omitempty"`
	Vars        map[string]interface{} `json:"vars,omitempty"`
}

https://docs.sentry.io/development/sdk-dev/interfaces/stacktrace/

func NewFrame 

func NewFrame(f runtime.Frame) Frame

NewFrame assembles a stacktrace frame out of `runtime.Frame`.

type Hub 

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

Hub is the central object that can 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) 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

Scope 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 invokes a function that can modify the current scope.

The function is passed a mutable reference to the `Scope` so that modifications can be performed.

func (*Hub) Flush 

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

Flush calls the method of a same name on currently bound `Client` instance.

func (*Hub) LastEventID 

func (hub *Hub) LastEventID() EventID

LastEventID returns an ID of last captured event for the current `Hub`.

func (*Hub) PopScope 

func (hub *Hub) PopScope()

PushScope pops the most recent scope for the current `Hub`.

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 temporarily pushes a scope for a single call.

A shorthand for: PushScope() f(scope) 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"
)

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

https://docs.sentry.io/development/sdk-dev/interfaces/http/

func (Request) FromHTTPRequest 

func (r Request) FromHTTPRequest(request *http.Request) Request

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:

  1. the scope is routinely updated with information by functions such as `AddBreadcrumb` which will modify the currently top-most scope.
  2. the topmost scope can also be configured through the `ConfigureScope` method.

Note that the scope can only be modified but not inspected. Only the client can use the scope to extract information currently.

func NewScope 

func NewScope() *Scope

func (*Scope) AddBreadcrumb 

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

AddBreadcrumb adds new breadcrumb to the current scope and optionaly 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) *Event

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

func (*Scope) Clear 

func (scope *Scope) Clear()

Clear removed the data 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 interface{})

SetContext adds a context to the current scope.

func (*Scope) SetContexts 

func (scope *Scope) SetContexts(contexts map[string]interface{})

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

func (scope *Scope) SetRequest(request Request)

SetRequest sets new user 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 new 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"`
}

https://docs.sentry.io/development/sdk-dev/interfaces/sdk/

type SdkPackage 

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

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` object. TODO: Make it configurable so that anyone can provide their own implementation? Use of reflection allows us to not have a hard dependency on any given package, so we don't have to import it

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"`
	RawStacktrace *Stacktrace `json:"raw_stacktrace,omitempty"`
	Crashed       bool        `json:"crashed,omitempty"`
	Current       bool        `json:"current,omitempty"`
}

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 {
	Email     string `json:"email,omitempty"`
	ID        string `json:"id,omitempty"`
	IPAddress string `json:"ip_address,omitempty"`
	Username  string `json:"username,omitempty"`
}

https://docs.sentry.io/development/sdk-dev/interfaces/user/

Source Files

View all Source files

Directories

Path Synopsis
echo module
example
basic
flush
gin
http
iris
martini
multiclient
negroni
recover
fasthttp module
fiber module
otel module
slog module
zerolog module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.