Implement flush with context (#935)

Co-authored-by: Michi Hoffmann <cleptric@users.noreply.github.com>
Co-authored-by: Giannis Gkiortzis <giannis.gkiortzis@sentry.io>

Author: 3 people

_examples/flush-with-context/main.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/getsentry/sentry-go"
+)
+
+func main() {
+	_ = sentry.Init(sentry.ClientOptions{
+		Dsn:   "https://hello@example.com/1337",
+		Debug: true,
+	})
+
+	sentry.CaptureMessage("Event #1")
+	sentry.CaptureMessage("Event #2")
+	sentry.CaptureMessage("Event #3")
+
+	go func() {
+		sentry.CaptureMessage("Event #4")
+		sentry.CaptureMessage("Event #5")
+	}()
+
+	fmt.Println("=> Flushing transport buffer")
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second*2)
+	defer cancel()
+
+	if sentry.FlushWithContext(ctx) {
+		fmt.Println("=> All queued events delivered!")
+	} else {
+		fmt.Println("=> Flush timeout reached")
+	}
+}

client.go

@@ -516,6 +516,25 @@ func (client *Client) Flush(timeout time.Duration) bool {
 	return client.Transport.Flush(timeout)
 }
 
+// FlushWithContext waits until the underlying Transport sends any buffered events
+// to the Sentry server, blocking for at most the duration specified by the context.
+// It returns false if the context is canceled before the events are sent. In such a case,
+// some events may not be delivered.
+//
+// FlushWithContext should be called before terminating the program to ensure no
+// events are unintentionally dropped.
+//
+// Avoid calling FlushWithContext indiscriminately after each call to CaptureEvent,
+// CaptureException, or CaptureMessage. To send events synchronously over the network,
+// configure the SDK to use HTTPSyncTransport during initialization with Init.
+
+func (client *Client) FlushWithContext(ctx context.Context) bool {
+	if client.batchLogger != nil {
+		client.batchLogger.Flush()
+	}
+	return client.Transport.FlushWithContext(ctx)
+}
+
 // Close clean up underlying Transport resources.
 //
 // Close should be called after Flush and before terminating the program

hub.go

@@ -365,6 +365,28 @@ func (hub *Hub) Flush(timeout time.Duration) bool {
 	return client.Flush(timeout)
 }
 
+// FlushWithContext waits until the underlying Transport sends any buffered events
+// to the Sentry server, blocking for at most the duration specified by the context.
+// It returns false if the context is canceled before the events are sent. In such a case,
+// some events may not be delivered.
+//
+// FlushWithContext should be called before terminating the program to ensure no
+// events are unintentionally dropped.
+//
+// Avoid calling FlushWithContext indiscriminately after each call to CaptureEvent,
+// CaptureException, or CaptureMessage. To send events synchronously over the network,
+// configure the SDK to use HTTPSyncTransport during initialization with Init.
+
+func (hub *Hub) FlushWithContext(ctx context.Context) bool {
+	client := hub.Client()
+
+	if client == nil {
+		return false
+	}
+
+	return client.FlushWithContext(ctx)
+}
+
 // 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

hub_test.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 	"sync"
 	"testing"
+	"time"
 
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
@@ -493,3 +494,62 @@ func TestConcurrentHubClone(t *testing.T) {
 		t.Errorf("Events mismatch (-want +got):\n%s", diff)
 	}
 }
+
+func TestHub_Flush(t *testing.T) {
+	hub, client, _ := setupHubTest()
+	transport := &MockTransport{}
+	client.Transport = transport
+
+	wantEvent := Event{Message: "something"}
+	hub.CaptureEvent(&wantEvent)
+	hub.Flush(20 * time.Millisecond)
+
+	gotEvents := transport.Events()
+	if len(gotEvents) != 1 {
+		t.Fatalf("expected 1 event, got %d", len(gotEvents))
+	}
+	if gotEvents[0].Message != wantEvent.Message {
+		t.Fatalf("expected message to be %v, got %v", wantEvent.Message, gotEvents[0].Message)
+	}
+}
+
+func TestHub_Flush_NoClient(t *testing.T) {
+	hub := NewHub(nil, nil)
+	flushed := hub.Flush(20 * time.Millisecond)
+
+	if flushed != false {
+		t.Fatalf("expected flush to be false, got %v", flushed)
+	}
+}
+
+func TestHub_FlushWithCtx_NoClient(t *testing.T) {
+	hub := NewHub(nil, nil)
+	cancelCtx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	flushed := hub.FlushWithContext(cancelCtx)
+
+	if flushed != false {
+		t.Fatalf("expected flush to be false, got %v", flushed)
+	}
+}
+
+func TestHub_FlushWithContext(t *testing.T) {
+	hub, client, _ := setupHubTest()
+	transport := &MockTransport{}
+	client.Transport = transport
+
+	wantEvent := Event{Message: "something"}
+	hub.CaptureEvent(&wantEvent)
+
+	cancelCtx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+	hub.FlushWithContext(cancelCtx)
+	defer cancel()
+
+	gotEvents := transport.Events()
+	if len(gotEvents) != 1 {
+		t.Fatalf("expected 1 event, got %d", len(gotEvents))
+	}
+	if gotEvents[0].Message != wantEvent.Message {
+		t.Fatalf("expected message to be %v, got %v", wantEvent.Message, gotEvents[0].Message)
+	}
+}

log_test.go

@@ -452,6 +452,21 @@ func Test_batchLogger_Flush(t *testing.T) {
 	}
 }
 
+func Test_batchLogger_FlushWithContext(t *testing.T) {
+	ctx, mockTransport := setupMockTransport()
+	l := NewLogger(context.Background())
+	l.Info(ctx, "context done log")
+
+	cancelCtx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+	FlushWithContext(cancelCtx)
+	defer cancel()
+
+	events := mockTransport.Events()
+	if len(events) != 1 {
+		t.Fatalf("expected 1 event, got %d", len(events))
+	}
+}
+
 func Test_sentryLogger_BeforeSendLog(t *testing.T) {
 	ctx := context.Background()
 	mockTransport := &MockTransport{}

logrus/README.md

@@ -102,5 +102,5 @@ This ensures that logs from specific contexts or threads use the appropriate Sen
 
 ## Notes
 
-- Always call Flush to ensure all events are sent to Sentry before program termination
+- Always call `Flush` or `FlushWithContext` to ensure all events are sent to Sentry before program termination
 

logrus/logrusentry.go

@@ -2,6 +2,7 @@
 package sentrylogrus
 
 import (
+	"context"
 	"errors"
 	"net/http"
 	"time"
@@ -222,3 +223,11 @@ func (h *Hook) entryToEvent(l *logrus.Entry) *sentry.Event {
 func (h *Hook) Flush(timeout time.Duration) bool {
 	return h.hubProvider().Client().Flush(timeout)
 }
+
+// FlushWithContext waits for the underlying Sentry transport to send any buffered
+// events, blocking until the context's deadline is reached or the context is canceled.
+// It returns false if the context is canceled or its deadline expires before the events
+// are sent, meaning some events may not have been sent.
+func (h *Hook) FlushWithContext(ctx context.Context) bool {
+	return h.hubProvider().Client().FlushWithContext(ctx)
+}

mocks.go

@@ -1,6 +1,7 @@
 package sentry
 
 import (
+	"context"
 	"sync"
 	"time"
 )
@@ -39,6 +40,7 @@ func (t *MockTransport) SendEvent(event *Event) {
 func (t *MockTransport) Flush(_ time.Duration) bool {
 	return true
 }
+func (t *MockTransport) FlushWithContext(_ context.Context) bool { return true }
 func (t *MockTransport) Events() []*Event {
 	t.mu.Lock()
 	defer t.mu.Unlock()

sentry.go

@@ -125,6 +125,23 @@ func Flush(timeout time.Duration) bool {
 	return hub.Flush(timeout)
 }
 
+// FlushWithContext waits until the underlying Transport sends any buffered events
+// to the Sentry server, blocking for at most the duration specified by the context.
+// It returns false if the context is canceled before the events are sent. In such a case,
+// some events may not be delivered.
+//
+// FlushWithContext should be called before terminating the program to ensure no
+// events are unintentionally dropped.
+//
+// Avoid calling FlushWithContext indiscriminately after each call to CaptureEvent,
+// CaptureException, or CaptureMessage. To send events synchronously over the network,
+// configure the SDK to use HTTPSyncTransport during initialization with Init.
+
+func FlushWithContext(ctx context.Context) bool {
+	hub := CurrentHub()
+	return hub.FlushWithContext(ctx)
+}
+
 // LastEventID returns an ID of last captured event.
 func LastEventID() EventID {
 	hub := CurrentHub()

slog/README.MD

@@ -90,4 +90,4 @@ handler := slogSentry.Option{
 
 ## Notes
 
-- Always call Flush to ensure all events are sent to Sentry before program termination
+- Always call `Flush` or `FlushWithContext` to ensure all events are sent to Sentry before program termination