191 lines
7.2 KiB
Markdown
191 lines
7.2 KiB
Markdown
<p align="center">
|
||
<a href="https://sentry.io" target="_blank" align="center">
|
||
<img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" width="280">
|
||
</a>
|
||
<br />
|
||
</p>
|
||
|
||
# Official Sentry SDK for Go
|
||
|
||
[](https://travis-ci.com/getsentry/sentry-go)
|
||
[](https://goreportcard.com/report/github.com/getsentry/sentry-go)
|
||
[](https://discord.gg/Ww9hbqr)
|
||
[](https://godoc.org/github.com/getsentry/sentry-go)
|
||
[](https://pkg.go.dev/github.com/getsentry/sentry-go)
|
||
|
||
`sentry-go` provides a Sentry client implementation for the Go programming
|
||
language. This is the next line of the Go SDK for [Sentry](https://sentry.io/),
|
||
intended to replace the `raven-go` package.
|
||
|
||
> Looking for the old `raven-go` SDK documentation? See the Legacy client section [here](https://docs.sentry.io/clients/go/).
|
||
> If you want to start using sentry-go instead, check out the [migration guide](https://docs.sentry.io/platforms/go/migration/).
|
||
|
||
## 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
|
||
[`.travis.yml`](.travis.yml).
|
||
|
||
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`:
|
||
|
||
```console
|
||
$ go get github.com/getsentry/sentry-go
|
||
```
|
||
|
||
Or, if you are already using
|
||
[Go Modules](https://github.com/golang/go/wiki/Modules), you may specify a
|
||
version number as well:
|
||
|
||
```console
|
||
$ go get github.com/getsentry/sentry-go@latest
|
||
```
|
||
|
||
Check out the [list of released versions](https://pkg.go.dev/github.com/getsentry/sentry-go?tab=versions).
|
||
|
||
## Configuration
|
||
|
||
To use `sentry-go`, you’ll need to import the `sentry-go` package and initialize
|
||
it with your DSN and other [options](https://godoc.org/github.com/getsentry/sentry-go#ClientOptions).
|
||
|
||
If not specified in the SDK initialization, the
|
||
[DSN](https://docs.sentry.io/error-reporting/configuration/?platform=go#dsn),
|
||
[Release](https://docs.sentry.io/workflow/releases/?platform=go) and
|
||
[Environment](https://docs.sentry.io/enriching-error-data/environments/?platform=go)
|
||
are read from the environment variables `SENTRY_DSN`, `SENTRY_RELEASE` and
|
||
`SENTRY_ENVIRONMENT`, respectively.
|
||
|
||
More on this in the [Configuration](https://docs.sentry.io/platforms/go/config/)
|
||
section of the official Sentry documentation.
|
||
|
||
## Usage
|
||
|
||
The SDK must be initialized with a call to `sentry.Init`. The default transport
|
||
is asynchronous and thus most programs should call `sentry.Flush` to wait until
|
||
buffered events are sent to Sentry right before the program terminates.
|
||
|
||
Typically, `sentry.Init` is called in the beginning of `func main` and
|
||
`sentry.Flush` is [deferred](https://golang.org/ref/spec#Defer_statements) right
|
||
after.
|
||
|
||
> Note that if the program terminates with a call to
|
||
> [`os.Exit`](https://golang.org/pkg/os/#Exit), either directly or indirectly
|
||
> via another function like `log.Fatal`, deferred functions are not run.
|
||
>
|
||
> In that case, and if it is important for you to report outstanding events
|
||
> before terminating the program, arrange for `sentry.Flush` to be called before
|
||
> the program terminates.
|
||
|
||
Example:
|
||
|
||
```go
|
||
// This is an example program that makes an HTTP request and prints response
|
||
// headers. Whenever a request fails, the error is reported to Sentry.
|
||
//
|
||
// Try it by running:
|
||
//
|
||
// go run main.go
|
||
// go run main.go https://sentry.io
|
||
// go run main.go bad-url
|
||
//
|
||
// To actually report events to Sentry, set the DSN either by editing the
|
||
// appropriate line below or setting the environment variable SENTRY_DSN to
|
||
// match the DSN of your Sentry project.
|
||
package main
|
||
|
||
import (
|
||
"fmt"
|
||
"log"
|
||
"net/http"
|
||
"os"
|
||
"time"
|
||
|
||
"github.com/getsentry/sentry-go"
|
||
)
|
||
|
||
func main() {
|
||
if len(os.Args) < 2 {
|
||
log.Fatalf("usage: %s URL", os.Args[0])
|
||
}
|
||
|
||
err := sentry.Init(sentry.ClientOptions{
|
||
// Either set your DSN here or set the SENTRY_DSN environment variable.
|
||
Dsn: "",
|
||
// Enable printing of SDK debug messages.
|
||
// Useful when getting started or trying to figure something out.
|
||
Debug: true,
|
||
})
|
||
if err != nil {
|
||
log.Fatalf("sentry.Init: %s", err)
|
||
}
|
||
// Flush buffered events before the program terminates.
|
||
// Set the timeout to the maximum duration the program can afford to wait.
|
||
defer sentry.Flush(2 * time.Second)
|
||
|
||
resp, err := http.Get(os.Args[1])
|
||
if err != nil {
|
||
sentry.CaptureException(err)
|
||
log.Printf("reported to Sentry: %s", err)
|
||
return
|
||
}
|
||
defer resp.Body.Close()
|
||
|
||
for header, values := range resp.Header {
|
||
for _, value := range values {
|
||
fmt.Printf("%s=%s\n", header, value)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
For your convenience, this example is available at
|
||
[`example/basic/main.go`](example/basic/main.go).
|
||
There are also more examples in the
|
||
[example](example) directory.
|
||
|
||
For more detailed information about how to get the most out of `sentry-go`,
|
||
checkout the official documentation:
|
||
|
||
- [Configuration](https://docs.sentry.io/platforms/go/config)
|
||
- [Error Reporting](https://docs.sentry.io/error-reporting/quickstart?platform=go)
|
||
- [Enriching Error Data](https://docs.sentry.io/enriching-error-data/context?platform=go)
|
||
- [Transports](https://docs.sentry.io/platforms/go/transports)
|
||
- [Integrations](https://docs.sentry.io/platforms/go/integrations)
|
||
- [net/http](https://docs.sentry.io/platforms/go/http)
|
||
- [echo](https://docs.sentry.io/platforms/go/echo)
|
||
- [fasthttp](https://docs.sentry.io/platforms/go/fasthttp)
|
||
- [gin](https://docs.sentry.io/platforms/go/gin)
|
||
- [iris](https://docs.sentry.io/platforms/go/iris)
|
||
- [martini](https://docs.sentry.io/platforms/go/martini)
|
||
- [negroni](https://docs.sentry.io/platforms/go/negroni)
|
||
|
||
## Resources
|
||
|
||
- [Bug Tracker](https://github.com/getsentry/sentry-go/issues)
|
||
- [GitHub Project](https://github.com/getsentry/sentry-go)
|
||
- [](https://godoc.org/github.com/getsentry/sentry-go)
|
||
- [](https://pkg.go.dev/github.com/getsentry/sentry-go)
|
||
- [](https://docs.sentry.io/platforms/go/)
|
||
- [](https://forum.sentry.io/c/sdks)
|
||
- [](https://discord.gg/Ww9hbqr)
|
||
- [](http://stackoverflow.com/questions/tagged/sentry)
|
||
- [](https://twitter.com/intent/follow?screen_name=getsentry)
|
||
|
||
|
||
## License
|
||
|
||
Licensed under
|
||
[The 2-Clause BSD License](https://opensource.org/licenses/BSD-2-Clause), see
|
||
[`LICENSE`](LICENSE).
|
||
|
||
## Community
|
||
|
||
Join Sentry's [`#go` channel on Discord](https://discord.gg/Ww9hbqr) to get
|
||
involved and help us improve the SDK!
|