feat(go): Structured logging support for slog & logrus (#14104)

giortzisg · bitsandfoxes · commit ba05f7a73283 · 2025-07-03T10:37:50.000+02:00
diff --git a/docs/platforms/go/common/logs/index.mdx b/docs/platforms/go/common/logs/index.mdx
@@ -120,9 +120,13 @@ slogger.Info("Implementing slog.Logger")
   Sentry UI.
 </Alert>
 
+### Integrations
+- [Slog](/platforms/go/guides/slog)
+- [Logrus](/platforms/go/guides/logrus)
+
 ### Upcoming Integrations
 
-We're actively working on adding more integration support for Logs. Currently we are looking at adding support for [`slog`](https://pkg.go.dev/log/slog), [`logrus`](https://pkg.go.dev/github.com/sirupsen/logrus), and [`zerolog`](https://pkg.go.dev/github.com/rs/zerolog). You can follow this [GitHub issue](https://github.com/getsentry/sentry-go/issues/1015) to track progress.
+We're actively working on adding more integration support for Logs. Currently, we are looking at adding support for [`zerolog`](https://pkg.go.dev/github.com/rs/zerolog). You can follow this [GitHub issue](https://github.com/getsentry/sentry-go/issues/1015) to track progress.
 
 ## Options
 
diff --git a/docs/platforms/go/common/usage/index.mdx b/docs/platforms/go/common/usage/index.mdx
@@ -32,3 +32,7 @@ Another common operation is to capture a bare message. A message is textual info
 Messages show up as issues on your issue stream, with the message as the issue name.
 
 <PlatformContent includePath="capture-message" />
+
+## Capturing Logs
+
+Another common operation is to capture logs. Check <PlatformLink to="/logs"> Logs </PlatformLink> for how to setup your logging integration to send log entries to Sentry.
diff --git a/docs/platforms/go/guides/logrus/index.mdx b/docs/platforms/go/guides/logrus/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: Logrus
-description: "Logrus is a structured logger for Go, used to log messages in different formats and levels. This guide demonstrates how to integrate Logrus with Sentry to capture and send logs to Sentry."
+description: "Logrus is a structured logger for Go, used to log messages in different formats and levels. This guide demonstrates how to integrate Logrus with Sentry to capture and send both logs and events to Sentry."
 ---
 
 For a quick reference, there is a [complete example](https://github.com/getsentry/sentry-go/tree/master/_examples/logrus) at the Go SDK source code repository.
@@ -17,6 +17,8 @@ go get github.com/getsentry/sentry-go/logrus
 
 <SignInNote />
 
+To integrate Sentry with Logrus, you can set up both log hooks and event hooks to capture different types of data at various log levels.
+
 ```go
 import (
 	"fmt"
@@ -25,61 +27,147 @@ import (
 	"time"
 
 	"github.com/sirupsen/logrus"
-
 	"github.com/getsentry/sentry-go"
 	sentrylogrus "github.com/getsentry/sentry-go/logrus"
 )
 
-    logger := logrus.New()
+func main() {
+	// Initialize Logrus
+	logger := logrus.New()
 
 	// Log DEBUG and higher level logs to STDERR
 	logger.Level = logrus.DebugLevel
 	logger.Out = os.Stderr
 
-	// Send only ERROR and higher level logs to Sentry
-	sentryLevels := []logrus.Level{logrus.ErrorLevel, logrus.FatalLevel, logrus.PanicLevel}
-
-	// Initialize Sentry
-	sentryHook, err := sentrylogrus.New(sentryLevels, sentry.ClientOptions{
+	// send logs on InfoLevel
+	logHook, err := sentrylogrus.NewLogHook(
+		[]logrus.Level{logrus.InfoLevel},
+		sentry.ClientOptions{
+			Dsn: "___PUBLIC_DSN___",
+			BeforeSend: func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
+				if hint.Context != nil {
+					if req, ok := hint.Context.Value(sentry.RequestContextKey).(*http.Request); ok {
+						// You have access to the original Request
+						fmt.Println(req)
+					}
+				}
+				fmt.Println(event)
+				return event
+			},
+			// need to have logs enabled
+			EnableLogs:       true,
+			AttachStacktrace: true,
+		})
+
+	// send events on Error, Fatal, Panic levels
+	eventHook, err := sentrylogrus.NewEventHook([]logrus.Level{
+		logrus.ErrorLevel,
+		logrus.FatalLevel,
+		logrus.PanicLevel,
+	}, sentry.ClientOptions{
 		Dsn: "___PUBLIC_DSN___",
 		BeforeSend: func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event {
 			if hint.Context != nil {
 				if req, ok := hint.Context.Value(sentry.RequestContextKey).(*http.Request); ok {
-					// Access the original Request here
+					// You have access to the original Request
 					fmt.Println(req)
 				}
 			}
 			fmt.Println(event)
 			return event
 		},
-		Debug:            true,
 		AttachStacktrace: true,
 	})
 	if err != nil {
 		panic(err)
 	}
-	defer sentryHook.Flush(5 * time.Second)
-	logger.AddHook(sentryHook)
+	defer eventHook.Flush(5 * time.Second)
+	defer logHook.Flush(5 * time.Second)
+	logger.AddHook(eventHook)
+	logger.AddHook(logHook)
 
 	// Flushes before calling os.Exit(1) when using logger.Fatal
 	// (else all defers are not called, and Sentry does not have time to send the event)
-	logrus.RegisterExitHandler(func() { sentryHook.Flush(5 * time.Second) })
-
-	// Log an InfoLevel entry to STDERR (not sent to Sentry)
-	logger.Infof("Application has started")
+	logrus.RegisterExitHandler(func() {
+		eventHook.Flush(5 * time.Second)
+		logHook.Flush(5 * time.Second)
+	})
 
-	// Log an ErrorLevel entry to STDERR and Sentry
-	logger.Errorf("oh no!")
+    // Log a InfoLevel entry STDERR which is sent as a log to Sentry
+    logger.Infof("Application has started")
 
-	// Log a FatalLevel entry to STDERR, send to Sentry, and terminate the application
-	logger.Fatalf("can't continue...")
+    // Log an error to STDERR which is also sent to Sentry
+    logger.Errorf("oh no!")
 
+    // Log a fatal error to STDERR, which sends an event to Sentry and terminates the application
+    logger.Fatalf("can't continue...")
+	
+    // Example of logging with attributes
+	logger.WithField("user", "test-user").Error("An error occurred")
+}
 ```
 
 ## Configure
 
-`sentrylogrus` allows configuration via the `New` function, which accepts the levels to log and `sentry.ClientOptions`. The levels to log are the logrus levels that should be sent to Sentry. The `sentry.ClientOptions` are the same as the ones used in the `sentry.Init` function.
+`sentrylogrus` provides two types of hooks to configure the integration with Sentry. Both hooks accept these options:
+- **Levels**: A slice of `logrus.Level` specifying which log levels to capture
+- **ClientOptions**: Standard `sentry.ClientOptions` for configuration
+
+### LogHook
+
+Use `sentrylogrus.NewLogHook()` to send structured logs to Sentry. This hook captures log entries and sends them to Sentry's structured logging system.
+
+```go
+logHook, err := sentrylogrus.NewLogHook(
+    []logrus.Level{logrus.InfoLevel, logrus.WarnLevel},
+    sentry.ClientOptions{
+        Dsn: "___PUBLIC_DSN___",
+        EnableLogs: true, // Required for log entries
+    })
+```
+
+### EventHook
+
+Use `sentrylogrus.NewEventHook()` to send log entries as Sentry events. This is useful for error tracking and alerting.
+
+```go
+eventHook, err := sentrylogrus.NewEventHook(
+    []logrus.Level{logrus.ErrorLevel, logrus.FatalLevel, logrus.PanicLevel},
+    sentry.ClientOptions{
+        Dsn: "___PUBLIC_DSN___",
+        Debug: true,
+        AttachStacktrace: true,
+    })
+```
+
+<Alert>
+    When using both hooks, ensure you flush both of them before the application exits and register exit handlers for fatal logs to avoid losing pending events.
+</Alert>
+
+## Correlating Logs with Traces
+
+To correlate logs with transactions, you need to pass a `context.Context` that contains transaction information to your logger calls. The `sentryhttp` middleware automatically adds transaction information to the request's context.
+Here's an example of how to use `WithContext` in an HTTP handler to ensure logs are associated with the correct trace.
+
+```go
+// Assume logger is initialized and Sentry hooks are added as shown above.
+// var logger *logrus.Logger
+
+func myAsyncHandler(w http.ResponseWriter, r *http.Request) {
+	// The sentryhttp middleware adds a Hub with transaction information to the request context.
+	ctx := r.Context()
+	// By using WithContext, the log entry will be associated with the transaction from the request.
+    logger.WithContext(ctx).Info("Log inside handler")
+	w.WriteHeader(http.StatusOK)
+	fmt.Fprintln(w, "Handler finished, async task running in background.")
+}
+
+// In your main function, or wherever you set up your routes:
+// Wrap your handler with sentryhttp to automatically start transactions for requests.
+sentryHandler := sentryhttp.New(sentryhttp.Options{})
+http.Handle("/async", sentryHandler.Handle(http.HandlerFunc(myAsyncHandler)))
+```
 
-## Usage
+## Logs
 
-Use `logrus` as you normally would, and it will automatically send logs at or above the specified levels to Sentry.
+For comprehensive logging setup with Logrus, including advanced configuration options and best practices, see the [Go Logs documentation](/platforms/go/logs/). The Logrus integration shown above provides seamless integration with Sentry's structured logging features.
diff --git a/docs/platforms/go/guides/slog/index.mdx b/docs/platforms/go/guides/slog/index.mdx
@@ -39,14 +39,20 @@ func main() {
 		// Adds request headers and IP for users,
 		// visit: https://docs.sentry.io/platforms/go/data-management/data-collected/ for more info
 		SendDefaultPII: true,
+		EnableLogs: true,
 	})
 	if err != nil {
 		log.Fatal(err)
 	}
 	defer sentry.Flush(2 * time.Second)
 
 	// Configure `slog` to use Sentry as a handler
-	logger := slog.New(sentryslog.Option{Level: slog.LevelDebug}.NewSentryHandler())
+	ctx := context.Background()
+	handler := sentryslog.Option{
+		EventLevel: []slog.Level{slog.LevelError, sentryslog.LevelFatal}, // Only Error and Fatal as events
+		LogLevel:   []slog.Level{slog.LevelWarn, slog.LevelInfo},         // Only Warn and Info as logs
+	}.NewSentryHandler(ctx)
+	logger := slog.New(handler)
 	logger = logger.With("release", "v1.0.0")
 
 	// Log messages with various attributes
@@ -59,7 +65,7 @@ func main() {
 		).
 		With("environment", "dev").
 		With("error", fmt.Errorf("an error")).
-		Error("a message")
+		ErrorContext(ctx, "a message")
 }
 ```
 
@@ -68,9 +74,14 @@ func main() {
 `sentryslog` provides options to configure the integration with Sentry. It accepts a struct of `sentryslog.Options` that allows you to configure how the handler will behave. The options are:
 
 ```go
-// Level sets the minimum log level to capture and send to Sentry.
-// Logs at this level and above will be processed. The default level is debug.
-Level slog.Leveler
+// EventLevel specifies the exact log levels to capture and send to Sentry as Events.
+// Only logs at these specific levels will be processed as events.
+// Defaults to []slog.Level{slog.LevelError, LevelFatal}.
+EventLevel slog.Leveler
+// LogLevel specifies the exact log levels to capture and send to Sentry as Log entries
+// Only logs at these specific levels will be processed as log entries.
+// Defaults to []slog.Level{slog.LevelDebug, slog.LevelInfo, slog.LevelWarn, slog.LevelError, LevelFatal}.
+LogLevel slog.Leveler
 // Hub specifies the Sentry Hub to use for capturing events.
 // If not provided, the current Hub is used by default.
 Hub *sentry.Hub
@@ -92,33 +103,69 @@ ReplaceAttr func(groups []string, a slog.Attr) slog.Attr
 
 ## Usage
 
+### Sending Logs vs Events
+
+Sentry allows you to send logs either as log entries or as events. The minimum log level defaults to `slog.LevelDebug` and logs will be sent if the `EnableLogs` option is set. The minimum event level defaults to `slog.LevelError`.
+
+### Example: Sending Logs as Events
+
 ```go
-logger := slog.New(sentryslog.Option{
-	Level: slog.LevelDebug,
+logger := slog.New(sentryslog.Options
+    EventLevel: []slog.Level{slog.LevelError, sentryslog.LevelFatal},
+    LogLevel: []slog.Level{}, // disable log entries
 	AttrFromContext: []func(ctx context.Context) []slog.Attr{
 		func(ctx context.Context) []slog.Attr {
 			return []slog.Attr{slog.String("request_id", "123")}
 		},
 	},
 }.NewSentryHandler())
 
-logger = logger.With("release", "v1.0.0")
-
-logger.
-	With(
-		slog.Group("user",
-			slog.String("id", "user-123"),
-			slog.Time("created_at", time.Now()),
-		),
-	).
-	With("environment", "dev").
-	With("error", fmt.Errorf("an error")).
-	Error("a message")
+logger.Error("This log is sent as an event")
 ```
 
+### Example: Sending Logs as Logs
+
+```go
+logger := slog.New(sentryslog.Options{
+	EventLevel: []slog.Level{}, // disable events
+    LogLevel:   []slog.Level{slog.LevelError},
+  },
+}.NewSentryHandler())
 
+logger.Error("This log is sent as a log")
+```
 
-<SignInNote />
+<Alert>
+    In order to properly attach the correct trace with each Log entry, a
+    `context.Context` is required. We recommend using `Context` functions to ensure your logs
+    are connected to spans and errors in the Sentry UI.
+</Alert>
 
+## Correlating Logs with Traces
+
+To correlate logs with transactions, you need to pass a `context.Context` that contains transaction information to your logger calls. The `sentryhttp` middleware automatically adds transaction information to the request's context.
+Here's an example of how to use `InfoContext` in an HTTP handler to ensure logs are associated with the correct trace.
+
+```go
+// Assume logger is initialized with the Sentry handler as shown above.
+// var logger *slog.Logger
+
+func myAsyncHandler(w http.ResponseWriter, r *http.Request) {
+	// The sentryhttp middleware adds a Hub with transaction information to the request context.
+	ctx := r.Context()
+	// By using InfoContext, the log entry will be associated with the transaction from the request.
+	logger.InfoContext(ctx, "Log inside handler")
+	w.WriteHeader(http.StatusOK)
+	fmt.Fprintln(w, "Handler finished, async task running in background.")
+}
+
+// Wrap your handler with sentryhttp to automatically start transactions for requests.
+sentryHandler := sentryhttp.New(sentryhttp.Options{})
+http.Handle("/async", sentryHandler.Handle(http.HandlerFunc(myAsyncHandler)))
+```
 
 Note: Ensure Sentry is flushed before the application exits to avoid losing any pending events.
+
+## Logs
+
+For comprehensive logging setup with slog, including advanced configuration options and best practices, see the [Go Logs documentation](/platforms/go/logs/). The slog integration shown above provides seamless integration with Sentry's structured logging features.
