Documentation ¶
Overview ¶
Package sentrywriter is a wrapper around the sentry-go package and implements the io.Writer interface. This allows us to send logs from zerolog (or some other logging package that accepts the io.Writer interface) and send them to Sentry (there is no dependency on zerolog in this package).
There is a mechanism in this package to filter json formatted logs (we normally only want to send errors to Sentry, rather than all logs). For example, let's say you supply the writer with a `LogLevel`:
errorLevel := sentrywriter.LogLevel{ MatchingString:"error", SentryLevel: sentry.ErrorLevel, } writer := sentrywriter.New(errorLevel)
The `writer` now has filtering turned on and when it next receives a log, it json decodes it and checks the `"level"` field (you can change this default using the `WithLevelFieldName` method) matches `"error"`. If it matches then it sets the sentry level to `sentry.ErrorLevel` and sends the message to Sentry. Multiple `LogLevel`s can be supplied both at instantiation time and at a later point, for example:
errorLevel := sentrywriter.LogLevel{ MatchingString: "error", SentryLevel: sentry.ErrorLevel, } fatalLevel := sentrywriter.LogLevel{ MatchingString: "fatal", SentryLevel: sentry.FatalLevel, } writer := sentrywriter.New(errorLevel, fatalLevel) warningLevel := sentrywriter.LogLevel{ MatchingString: "warning", SentryLevel: sentry.WarningLevel, } writer.WithLogLevel(warningLevel)
If no `LogLevel`s are provided then filtering is not turned on.
Here is a typical example, using zerolog. It is important to defer the `sentryWriter.Flush` function because the messages are sent to Sentry asynchronously.
package main import ( "github.com/getsentry/sentry-go" "github.com/mec07/sentrywriter" "github.com/rs/zerolog" "github.com/rs/zerolog/log" ) func main() { errorLevel := sentrywriter.LogLevel{"error", sentry.LevelError} sentryWriter, err := sentrywriter.New(errorLevel).WithUserID("userID").SetDSN("your-project-sentry-dsn") if err != nil { log.Error().Err(err).Str("dsn", "your-project-sentry-dsn").Msg("sentrywriter.SentryWriter.SetDSN") return } defer sentryWriter.Flush() consoleWriter := zerolog.ConsoleWriter{Out: os.Stdout} log.Logger = log.Output(zerolog.MultiLevelWriter(consoleWriter, sentryWriter)) }
More sentry options can be set by using the `SetClientOptions(sentry.ClientOptions)` method instead of the `SetDSN(string)` method. See https://godoc.org/github.com/getsentry/sentry-go#ClientOptions for full details on all the available options. Here is an example:
package main import ( "github.com/getsentry/sentry-go" "github.com/mec07/sentrywriter" "github.com/rs/zerolog" "github.com/rs/zerolog/log" ) func main() { errorLevel := sentrywriter.LogLevel{"error", sentry.LevelError} options := sentry.ClientOptions{ Dsn: "your-project-sentry-dsn", AttachStacktrace: true, Environment: "your-environment", Release: "the-version-of-this-release", } sentryWriter, err := sentrywriter.New(errorLevel).WithUserID("userID").SetClientOptions(options) if err != nil { log.Error().Err(err).Str("dsn", "your-project-sentry-dsn").Msg("sentrywriter.SentryWriter.SetDSN") return } defer sentryWriter.Flush(2 * time.Second) consoleWriter := zerolog.ConsoleWriter{Out: os.Stdout} log.Logger = log.Output(zerolog.MultiLevelWriter(consoleWriter, sentryWriter)) }
Also see `example/main.go`.
Index ¶
- type LogLevel
- type SentryClient
- type SentryWriter
- func (s *SentryWriter) Flush(timeout time.Duration) bool
- func (s *SentryWriter) SetClientOptions(options sentry.ClientOptions) (*SentryWriter, error)
- func (s *SentryWriter) SetDSN(DSN string) (*SentryWriter, error)
- func (s *SentryWriter) WithBreadcrumbs(limit int) *SentryWriter
- func (s *SentryWriter) WithClient(client SentryClient) *SentryWriter
- func (s *SentryWriter) WithLevelFieldName(name string) *SentryWriter
- func (s *SentryWriter) WithLogLevel(logLevel LogLevel) *SentryWriter
- func (s *SentryWriter) WithUserID(userID string) *SentryWriter
- func (s *SentryWriter) Write(log []byte) (int, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LogLevel ¶
type LogLevel struct { MatchingString string SentryLevel sentry.Level }
LogLevel is used to match the log level that you're using and then map it into a Sentry log level. For example, you may be logging at level "error", which corresponds to sentry.LevelError, so that would correspond to:
levelError := LogLevel{"error", sentry.LevelError}
See https://godoc.org/github.com/getsentry/sentry-go#Level for the possible Sentry log levels.
type SentryClient ¶
type SentryClient interface { CaptureMessage(message string, hint *sentry.EventHint, scope sentry.EventModifier) *sentry.EventID Flush(timeout time.Duration) bool }
SentryClient is an interface which represents the sentry-go package client.
type SentryWriter ¶
type SentryWriter struct {
// contains filtered or unexported fields
}
SentryWriter implements the io.Writer interface. It is a wrapper over the sentry-go client and sends the supplied logs of the specified log level to Sentry. It assumes that the logs are json encoded. Writes are asynchronous, so remember to call Flush before exiting the program.
func New ¶
func New(logLevels ...LogLevel) *SentryWriter
New returns a pointer to the SentryWriter, with the specified log levels set. The SentryWriter will write logs which match any of the supplied logs to Sentry. The default field that is checked for the log level is "level". For example:
writer := sentrywriter.New(sentrywriter.LogLevel{"error", sentry.LevelError})
func (*SentryWriter) Flush ¶
func (s *SentryWriter) Flush(timeout time.Duration) bool
Flush initiates the Flush method of the underlying Sentry client. Call this before exiting your program. The provided timeout is the maximum length of time to block until all the logs have been sent to Sentry. It returns false if the timeout is reached, which may signify that not all messages were sent to Sentry.
func (*SentryWriter) SetClientOptions ¶ added in v0.3.0
func (s *SentryWriter) SetClientOptions(options sentry.ClientOptions) (*SentryWriter, error)
SetClientOptions creates a new Sentry client with the supplied sentry.ClientOptions. For example:
writer, err := sentrywriter.New().SetClientOptions(sentry.ClientOptions{Dsn: "dsn"})
func (*SentryWriter) SetDSN ¶
func (s *SentryWriter) SetDSN(DSN string) (*SentryWriter, error)
SetDSN creates a new Sentry client with the supplied DSN. For example:
writer, err := sentrywriter.New().SetDSN(dsn, true)
func (*SentryWriter) WithBreadcrumbs ¶ added in v0.2.0
func (s *SentryWriter) WithBreadcrumbs(limit int) *SentryWriter
WithBreadcrumbs turns on storing breadcrumbs. This means that all the logs that would otherwise be discarded due to filtering (i.e. this feature is only used if filtering of json logs with LogLevels is used) get stored as breadcrumbs. The breadcrumbs are cleared as soon as a log is actually sent to Sentry. For example:
writer := sentrywriter.New().WithBreadcrumbs(20)
func (*SentryWriter) WithClient ¶
func (s *SentryWriter) WithClient(client SentryClient) *SentryWriter
WithClient allows you to substitute the client that is being used, rather than the default client from the sentry-go package. For example:
writer := sentrywriter.New().WithClient(client)
where client implements the SentryClient interface.
func (*SentryWriter) WithLevelFieldName ¶
func (s *SentryWriter) WithLevelFieldName(name string) *SentryWriter
WithLevelFieldName allows you to change the log level field name from the default of "level" to whatever you are using. For example:
writer := sentrywriter.New().WithLevelFieldName("log_level")
func (*SentryWriter) WithLogLevel ¶
func (s *SentryWriter) WithLogLevel(logLevel LogLevel) *SentryWriter
WithLogLevel adds a LogLevel that triggers an event to be sent to Sentry. For example:
writer := sentrywriter.New().WithLogLevel(sentrywriter.LogLevel{"error", sentry.LevelError})
func (*SentryWriter) WithUserID ¶
func (s *SentryWriter) WithUserID(userID string) *SentryWriter
WithUserID sets a user ID that will be reported alongside each Sentry event. This is helpful for code that runs on client machines. For example:
writer := sentrywriter.New().WithUserID("userID")