feat: add support for client reports (#1192)

Author: giortzisg

client.go

@@ -19,6 +19,7 @@ import (
 	"github.com/getsentry/sentry-go/internal/protocol"
 	"github.com/getsentry/sentry-go/internal/ratelimit"
 	"github.com/getsentry/sentry-go/internal/telemetry"
+	"github.com/getsentry/sentry-go/report"
 )
 
 // The identifier of the SDK.
@@ -258,6 +259,8 @@ type ClientOptions struct {
 	EnableLogs bool
 	// DisableMetrics controls when metrics should be emitted.
 	DisableMetrics bool
+	// DisableClientReports controls when client reports should be emitted.
+	DisableClientReports bool
 	// TraceIgnoreStatusCodes is a list of HTTP status codes that should not be traced.
 	// Each element can be either:
 	// - A single-element slice [code] for a specific status code
@@ -296,6 +299,8 @@ type Client struct {
 	batchLogger        *logBatchProcessor
 	batchMeter         *metricBatchProcessor
 	telemetryProcessor *telemetry.Processor
+	reportRecorder     report.ClientReportRecorder
+	reportProvider     report.ClientReportProvider
 }
 
 // NewClient creates and returns an instance of Client configured using
@@ -393,10 +398,18 @@ func NewClient(options ClientOptions) (*Client, error) {
 	}
 
 	client := Client{
-		options:       options,
-		dsn:           dsn,
-		sdkIdentifier: sdkIdentifier,
-		sdkVersion:    SDKVersion,
+		options:        options,
+		dsn:            dsn,
+		sdkIdentifier:  sdkIdentifier,
+		sdkVersion:     SDKVersion,
+		reportRecorder: report.NoopRecorder(),
+		reportProvider: report.NoopProvider(),
+	}
+
+	if !options.DisableClientReports {
+		a := report.NewAggregator()
+		client.reportRecorder = a
+		client.reportProvider = a
 	}
 
 	client.setupTransport()
@@ -430,7 +443,23 @@ func (client *Client) setupTransport() {
 		if opts.Dsn == "" {
 			transport = new(noopTransport)
 		} else {
-			transport = NewHTTPTransport()
+			httpTransport := NewHTTPTransport()
+			httpTransport.recorder = client.reportRecorder
+			httpTransport.provider = client.reportProvider
+			transport = httpTransport
+		}
+	} else {
+		// For known transport types, inject the client report interfaces.
+		switch tr := transport.(type) {
+		case *HTTPTransport:
+			tr.recorder = client.reportRecorder
+			tr.provider = client.reportProvider
+		case *HTTPSyncTransport:
+			tr.recorder = client.reportRecorder
+			tr.provider = client.reportProvider
+		case *internalAsyncTransportAdapter:
+			tr.recorder = client.reportRecorder
+			tr.provider = client.reportProvider
 		}
 	}
 
@@ -470,23 +499,25 @@ func (client *Client) setupTelemetryProcessor() { // nolint: unused
 		HTTPProxy:     client.options.HTTPProxy,
 		HTTPSProxy:    client.options.HTTPSProxy,
 		CaCerts:       client.options.CaCerts,
+		Recorder:      client.reportRecorder,
+		Provider:      client.reportProvider,
 	})
 	client.Transport = &internalAsyncTransportAdapter{transport: transport}
 
 	buffers := map[ratelimit.Category]telemetry.Buffer[protocol.TelemetryItem]{
-		ratelimit.CategoryError:       telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryError, 100, telemetry.OverflowPolicyDropOldest, 1, 0),
-		ratelimit.CategoryTransaction: telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryTransaction, 1000, telemetry.OverflowPolicyDropOldest, 1, 0),
-		ratelimit.CategoryLog:         telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryLog, 10*100, telemetry.OverflowPolicyDropOldest, 100, 5*time.Second),
-		ratelimit.CategoryMonitor:     telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryMonitor, 100, telemetry.OverflowPolicyDropOldest, 1, 0),
-		ratelimit.CategoryTraceMetric: telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryTraceMetric, 10*100, telemetry.OverflowPolicyDropOldest, 100, 5*time.Second),
+		ratelimit.CategoryError:       telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryError, 100, telemetry.OverflowPolicyDropOldest, 1, 0, client.reportRecorder),
+		ratelimit.CategoryTransaction: telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryTransaction, 1000, telemetry.OverflowPolicyDropOldest, 1, 0, client.reportRecorder),
+		ratelimit.CategoryLog:         telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryLog, 10*100, telemetry.OverflowPolicyDropOldest, 100, 5*time.Second, client.reportRecorder),
+		ratelimit.CategoryMonitor:     telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryMonitor, 100, telemetry.OverflowPolicyDropOldest, 1, 0, client.reportRecorder),
+		ratelimit.CategoryTraceMetric: telemetry.NewRingBuffer[protocol.TelemetryItem](ratelimit.CategoryTraceMetric, 10*100, telemetry.OverflowPolicyDropOldest, 100, 5*time.Second, client.reportRecorder),
 	}
 
 	sdkInfo := &protocol.SdkInfo{
 		Name:    client.sdkIdentifier,
 		Version: client.sdkVersion,
 	}
 
-	client.telemetryProcessor = telemetry.NewProcessor(buffers, transport, &client.dsn.Dsn, sdkInfo)
+	client.telemetryProcessor = telemetry.NewProcessor(buffers, transport, &client.dsn.Dsn, sdkInfo, client.reportRecorder)
 }
 
 func (client *Client) setupIntegrations() {
@@ -572,21 +603,27 @@ func (client *Client) captureLog(log *Log, _ *Scope) bool {
 	}
 
 	if client.options.BeforeSendLog != nil {
+		approxSize := log.ApproximateSize()
 		log = client.options.BeforeSendLog(log)
 		if log == nil {
 			debuglog.Println("Log dropped due to BeforeSendLog callback.")
+			client.reportRecorder.RecordOne(report.ReasonBeforeSend, ratelimit.CategoryLog)
+			client.reportRecorder.Record(report.ReasonBeforeSend, ratelimit.CategoryLogByte, int64(approxSize))
 			return false
 		}
 	}
 
 	if client.telemetryProcessor != nil {
 		if !client.telemetryProcessor.Add(log) {
 			debuglog.Print("Dropping log: telemetry buffer full or category missing")
+			// Note: processor tracks client report
 			return false
 		}
 	} else if client.batchLogger != nil {
 		if !client.batchLogger.Send(log) {
 			debuglog.Printf("Dropping log [%s]: buffer full", log.Level)
+			client.reportRecorder.RecordOne(report.ReasonBufferOverflow, ratelimit.CategoryLog)
+			client.reportRecorder.Record(report.ReasonBufferOverflow, ratelimit.CategoryLogByte, int64(log.ApproximateSize()))
 			return false
 		}
 	}
@@ -603,18 +640,21 @@ func (client *Client) captureMetric(metric *Metric, _ *Scope) bool {
 		metric = client.options.BeforeSendMetric(metric)
 		if metric == nil {
 			debuglog.Println("Metric dropped due to BeforeSendMetric callback.")
+			client.reportRecorder.RecordOne(report.ReasonBeforeSend, ratelimit.CategoryTraceMetric)
 			return false
 		}
 	}
 
 	if client.telemetryProcessor != nil {
 		if !client.telemetryProcessor.Add(metric) {
 			debuglog.Printf("Dropping metric: telemetry buffer full or category missing")
+			// Note: processor tracks client report
 			return false
 		}
 	} else if client.batchMeter != nil {
 		if !client.batchMeter.Send(metric) {
 			debuglog.Printf("Dropping metric %q: buffer full", metric.Name)
+			client.reportRecorder.RecordOne(report.ReasonBufferOverflow, ratelimit.CategoryTraceMetric)
 			return false
 		}
 	}
@@ -823,6 +863,7 @@ func (client *Client) processEvent(event *Event, hint *EventHint, scope EventMod
 	// (errors, messages) are sampled here. Does not apply to check-ins.
 	if event.Type != transactionType && event.Type != checkInType && !sample(client.options.SampleRate) {
 		debuglog.Println("Event dropped due to SampleRate hit.")
+		client.reportRecorder.RecordOne(report.ReasonSampleRate, event.toCategory())
 		return nil
 	}
 
@@ -837,16 +878,25 @@ func (client *Client) processEvent(event *Event, hint *EventHint, scope EventMod
 	switch event.Type {
 	case transactionType:
 		if client.options.BeforeSendTransaction != nil {
-			if event = client.options.BeforeSendTransaction(event, hint); event == nil {
+			spanCountBefore := event.GetSpanCount()
+			event = client.options.BeforeSendTransaction(event, hint)
+			if event == nil {
 				debuglog.Println("Transaction dropped due to BeforeSendTransaction callback.")
+				client.reportRecorder.RecordOne(report.ReasonBeforeSend, ratelimit.CategoryTransaction)
+				client.reportRecorder.Record(report.ReasonBeforeSend, ratelimit.CategorySpan, int64(spanCountBefore))
 				return nil
 			}
+			// Track spans removed by the callback
+			if droppedSpans := spanCountBefore - event.GetSpanCount(); droppedSpans > 0 {
+				client.reportRecorder.Record(report.ReasonBeforeSend, ratelimit.CategorySpan, int64(droppedSpans))
+			}
 		}
 	case checkInType: // not a default case, since we shouldn't apply BeforeSend on check-in events
 	default:
 		if client.options.BeforeSend != nil {
 			if event = client.options.BeforeSend(event, hint); event == nil {
 				debuglog.Println("Event dropped due to BeforeSend callback.")
+				client.reportRecorder.RecordOne(report.ReasonBeforeSend, ratelimit.CategoryError)
 				return nil
 			}
 		}
@@ -917,20 +967,44 @@ func (client *Client) prepareEvent(event *Event, hint *EventHint, scope EventMod
 
 	for _, processor := range client.eventProcessors {
 		id := event.EventID
+		category := event.toCategory()
+		spanCountBefore := event.GetSpanCount()
 		event = processor(event, hint)
 		if event == nil {
 			debuglog.Printf("Event dropped by one of the Client EventProcessors: %s\n", id)
+			client.reportRecorder.RecordOne(report.ReasonEventProcessor, category)
+			if category == ratelimit.CategoryTransaction {
+				client.reportRecorder.Record(report.ReasonEventProcessor, ratelimit.CategorySpan, int64(spanCountBefore))
+			}
 			return nil
 		}
+		// Track spans removed by the processor
+		if category == ratelimit.CategoryTransaction {
+			if droppedSpans := spanCountBefore - event.GetSpanCount(); droppedSpans > 0 {
+				client.reportRecorder.Record(report.ReasonEventProcessor, ratelimit.CategorySpan, int64(droppedSpans))
+			}
+		}
 	}
 
 	for _, processor := range globalEventProcessors {
 		id := event.EventID
+		category := event.toCategory()
+		spanCountBefore := event.GetSpanCount()
 		event = processor(event, hint)
 		if event == nil {
 			debuglog.Printf("Event dropped by one of the Global EventProcessors: %s\n", id)
+			client.reportRecorder.RecordOne(report.ReasonEventProcessor, category)
+			if category == ratelimit.CategoryTransaction {
+				client.reportRecorder.Record(report.ReasonEventProcessor, ratelimit.CategorySpan, int64(spanCountBefore))
+			}
 			return nil
 		}
+		// Track spans removed by the processor
+		if category == ratelimit.CategoryTransaction {
+			if droppedSpans := spanCountBefore - event.GetSpanCount(); droppedSpans > 0 {
+				client.reportRecorder.Record(report.ReasonEventProcessor, ratelimit.CategorySpan, int64(droppedSpans))
+			}
+		}
 	}
 
 	return event

client_reports_test.go

@@ -0,0 +1,105 @@
+package sentry
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/getsentry/sentry-go/internal/ratelimit"
+	"github.com/getsentry/sentry-go/internal/testutils"
+	"github.com/getsentry/sentry-go/report"
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+)
+
+// TestClientReports_Integration tests that client reports are properly generated
+// and sent when events are dropped for various reasons.
+func TestClientReports_Integration(t *testing.T) {
+	var receivedBodies [][]byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		receivedBodies = append(receivedBodies, body)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"id":"test-event-id"}`))
+	}))
+	defer srv.Close()
+
+	dsn := strings.Replace(srv.URL, "//", "//test@", 1) + "/1"
+	hub := CurrentHub().Clone()
+	c, err := NewClient(ClientOptions{
+		Dsn:                  dsn,
+		DisableClientReports: false,
+		SampleRate:           1.0,
+		BeforeSend: func(event *Event, _ *EventHint) *Event {
+			if event.Message == "drop-me" {
+				return nil
+			}
+			return event
+		},
+	})
+	if err != nil {
+		t.Fatalf("Init failed: %v", err)
+	}
+	hub.BindClient(c)
+	defer hub.Flush(testutils.FlushTimeout())
+
+	// second client with disabled reports shouldn't affect the first
+	_, _ = NewClient(ClientOptions{
+		Dsn:                  testDsn,
+		DisableClientReports: true,
+	})
+
+	// simulate dropped events for report outcomes
+	hub.CaptureMessage("drop-me")
+	scope := NewScope()
+	scope.AddEventProcessor(func(event *Event, _ *EventHint) *Event {
+		if event.Message == "processor-drop" {
+			return nil
+		}
+		return event
+	})
+	hub.WithScope(func(s *Scope) {
+		s.eventProcessors = scope.eventProcessors
+		hub.CaptureMessage("processor-drop")
+	})
+
+	hub.CaptureMessage("hi") // send an event to capture the report along with it
+	if !hub.Flush(testutils.FlushTimeout()) {
+		t.Fatal("Flush timed out")
+	}
+
+	var got report.ClientReport
+	found := false
+	for _, b := range receivedBodies {
+		for _, line := range bytes.Split(b, []byte("\n")) {
+			if json.Unmarshal(line, &got) == nil && len(got.DiscardedEvents) > 0 {
+				found = true
+				break
+			}
+		}
+		if found {
+			break
+		}
+	}
+	if !found {
+		t.Fatal("no client report found in envelope bodies")
+	}
+
+	if got.Timestamp.IsZero() {
+		t.Error("client report missing timestamp")
+	}
+
+	want := []report.DiscardedEvent{
+		{Reason: report.ReasonBeforeSend, Category: ratelimit.CategoryError, Quantity: 1},
+		{Reason: report.ReasonEventProcessor, Category: ratelimit.CategoryError, Quantity: 1},
+	}
+	if diff := cmp.Diff(want, got.DiscardedEvents, cmpopts.SortSlices(func(a, b report.DiscardedEvent) bool {
+		return a.Reason < b.Reason
+	})); diff != "" {
+		t.Errorf("DiscardedEvents mismatch (-want +got):\n%s", diff)
+	}
+}