Skip to content
SDKs

Go SDK

Report errors and panics from Go services with request context.

Watch the Go SDK video

A 2:37 walkthrough of this guide’s documented setup, examples, and SDK options. British male narration and captions are included.

2:37 · English narration · Captions includedOpen video

Jump to a chapter

Read the video transcript
Install and initialize

Install the Go module with the command in the guide. Go one point twenty-one or newer is required. Initialize before accepting requests, using the Cloud HTTPS endpoint or your Enterprise Agent URL. Pass Endpoint, Node ID, and Ingest Key explicitly. The SDK can read release and commit SHA from the corresponding Reelay environment variables. The main dot Go example initializes first, then defers Flush.

HTTP and error context

Wrap your HTTP router with Reelay Middleware, as shown in main dot Go. Middleware panics if called before Init, so initialize first. To verify, add the documented Reelay test handler in staging and hit it with curl. Middleware reports the panic and returns a five hundred response. Then check the event in Errors.

Go has no ambient request store. Middleware seeds context into the request’s Context method; pass that context to every SDK call. In the guide’s save Order example, check the returned error, append the Order could not be saved log, and call Capture Exception with the same request context. The API reference also lists Capture Message and Add Breadcrumb for reporting conditions and attaching evidence.

Sampling, profiling, and jobs

Sample Rate is a float pointer; nil sends every error. Before Send filters a scrubbed event and returns nil to drop it. Extra scrub Patterns redact your own formats. Trace sampling is also a float pointer: nil or zero leaves it off. The performance example sets a sample variable to zero point one, passes its address, and enables Profiling for wall-clock profiles.

The API reference lists With Span for timing a child operation in a sampled transaction, and With Transaction for timing a job. Set Transaction Name gives requests a useful name. With Monitor and Check In report scheduled-job check-ins. New Transport and Wrap Client instrument outbound HTTP requests with spans and trace propagation. Use the reference on this page for these functions.

Panic recovery and shutdown

For goroutine panics, defer Recover to report and re-panic, or defer Recover And Continue to report and swallow. A recovered function returns. The worker example places recovery around each job invocation so the outer loop can continue. For a bounded full telemetry shutdown, call Close with a deadline context; it returns whether delivery drained in time. Flush drains the pending error queue before exit.

Install

Requires Go 1.21+. Initialize before accepting requests. Use https://api.usereelay.com for Cloud, or your Enterprise Agent URL.

The SDK reads REELAY_RELEASE and REELAY_COMMIT_SHA from the environment. Everything else — Endpoint, NodeID, IngestKey — must be passed in Options explicitly.

Install
go get github.com/OpenResearchGuys/reelay-go-sdk
main.go
package main
import (
"log"
"net/http"
"os"
reelay "github.com/OpenResearchGuys/reelay-go-sdk"
)
func main() {
reelay.Init(reelay.Options{
Endpoint: os.Getenv("REELAY_INGEST_ENDPOINT"),
NodeID: os.Getenv("REELAY_NODE_ID"),
IngestKey: os.Getenv("REELAY_INGEST_KEY"),
})
defer reelay.Flush()
mux := http.NewServeMux()
mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
})
if err := http.ListenAndServe(":3000", reelay.Middleware()(mux)); err != nil {
log.Print(err)
}
}

Verify it works

Add a test handler in staging, hit it, and check the event in Errors. The middleware reports the panic and returns a 500.

Test handler
mux.HandleFunc("/reelay-test", func(w http.ResponseWriter, r *http.Request) {
panic("Reelay test")
})
Hit it
curl http://localhost:3000/reelay-test

Pass the request context

Go has no ambient request store, so the SDK uses context.Context. The middleware seeds it into r.Context(); pass that to every SDK call.

Manual capture
if err := saveOrder(r.Context()); err != nil {
reelay.AppendLog(r.Context(), "error", "Order could not be saved")
reelay.CaptureException(r.Context(), err)
}

Options

OptionUse
EndpointHTTPS ingest URL. Required.
NodeID, IngestKeyNode credentials. Required by the backend.
Release, CommitSHADeployed version and full Git SHA. Also read from REELAY_RELEASE / REELAY_COMMIT_SHA.
SampleRate*float64 error sampling. nil = 1 (send every error).
BeforeSendFilter a scrubbed event. Return nil to drop.
ScrubPatternsExtra regexes to redact.
TracesSampleRate*float64 transaction sampling. nil or 0 = off.
ProfilingWall-clock profiling. Requires TracesSampleRate > 0. Default: false.
DebugDiagnostic callback.

Performance monitoring

Set TracesSampleRate above 0 to record a sampled share of requests as transactions. Set Profiling: true alongside it for wall-clock profiles.

Tracing and profiling
sample := 0.1
reelay.Init(reelay.Options{
Endpoint: os.Getenv("REELAY_INGEST_ENDPOINT"),
NodeID: os.Getenv("REELAY_NODE_ID"),
IngestKey: os.Getenv("REELAY_INGEST_KEY"),
TracesSampleRate: &sample,
Profiling: true,
})

Panics outside HTTP

Middleware recovers panics in HTTP handlers. For goroutines, use defer reelay.Recover(ctx) to report and re-panic (fatal), or defer reelay.RecoverAndContinue(ctx) to report and swallow. A recovered function returns; put recovery around one job invocation when the outer worker loop should continue.

Worker goroutine
func worker(ctx context.Context, jobs <-chan Job) {
for j := range jobs {
func() {
defer reelay.RecoverAndContinue(ctx)
process(j)
}()
}
}

SDK API reference

Call Close with a deadline when you need bounded shutdown, including profiling and telemetry. RecoverAndContinue changes panic behavior, so use it only where continuing the worker is intentional.

FunctionPurpose
Init(options), GetClient()Initialize the client once or get the active client.
Middleware()Wrap an HTTP handler with request context and panic reporting. Panics if called before Init().
CaptureException(ctx, err), CaptureMessage(ctx, message)Report a handled failure or noteworthy condition. err is any value; non-errors are stringified.
AppendLog(ctx, level, message), AddBreadcrumb(ctx, crumb)Attach useful evidence to a request context.
AppendSpan(ctx, span)Add a timeline span ({ span_id, name, status? }) to the active request's error timeline.
StartSpan(ctx, category, name)Start a manual timeline span; returns a function to seal it with a final status.
Recover(ctx)Use with defer to report a panic and re-panic.
RecoverAndContinue(ctx)Use with defer only when a worker should report and swallow the panic.
WithSpan(ctx, op, description, fn)Time fn as a child span of the active sampled transaction.
WithTransaction(ctx, name, op, fn)Time a job or other operation as its own transaction.
SetTransactionName(ctx, name)Set a useful transaction name, such as a route pattern.
WithMonitor(ctx, slug, config, fn), CheckIn(payload)Report scheduled-job check-ins.
NewTransport(base), WrapClient(client)Instrument outbound net/http requests with spans and trace propagation.
Flush()Drain the pending error queue before exit.
Close(ctx)Bound a full telemetry shutdown by context; returns whether it drained in time.