feat(go): refactor tracing docs (#16172)

Author: giortzisg

docs/platforms/go/common/logs/index.mdx

@@ -38,3 +38,5 @@ If the `Debug` init option is set to true, calls to the `sentry.Logger` will als
 ## Other Logging Integrations
 
 <PlatformContent includePath="logs/integrations" />
+
+<PageGrid />

docs/platforms/go/guides/logrus/index.mdx docs/platforms/go/common/logs/logrus.mdxdocs/platforms/go/guides/logrus/index.mdx renamed to docs/platforms/go/common/logs/logrus.mdx

@@ -1,6 +1,7 @@
 ---
 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 both logs and events to Sentry."
+description: "Integrate Logrus with Sentry to capture and send both logs and events."
+sidebar_order: 10
 ---
 
 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.
@@ -178,11 +179,3 @@ if client != nil {
 </Alert>
 
 <Include name="logs/go-ctx-usage-alert.mdx"/>
-
-## Logs
-
-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.
-
-## Next Steps
-
-- Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup

docs/platforms/go/guides/slog/index.mdx docs/platforms/go/common/logs/slog.mdxdocs/platforms/go/guides/slog/index.mdx renamed to docs/platforms/go/common/logs/slog.mdx

@@ -1,6 +1,7 @@
 ---
 title: Slog
-description: "Slog is a structured logging library for Go, introduced in Go 1.21. This guide demonstrates how to integrate slog with Sentry to capture and send logs to Sentry."
+description: "Integrate slog with Sentry to capture and send structured logs."
+sidebar_order: 20
 ---
 
 For a quick reference, there is a [complete example](https://github.com/getsentry/sentry-go/tree/master/_examples/slog) at the Go SDK source code repository.
@@ -84,11 +85,3 @@ logger.With("key.string", "value").Info("An error occurred")
 ```
 
 <Include name="logs/go-ctx-usage-alert.mdx"/>
-
-## 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.
-
-## Next Steps
-
-- Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup

docs/platforms/go/guides/zap/index.mdx docs/platforms/go/common/logs/zap.mdxdocs/platforms/go/guides/zap/index.mdx renamed to docs/platforms/go/common/logs/zap.mdx

@@ -1,6 +1,7 @@
 ---
 title: Zap
-description: "Zap is a blazing-fast, structured logging library for Go. This guide demonstrates how to integrate zap with Sentry to capture and send logs to Sentry."
+description: "Integrate Zap with Sentry to capture and send structured logs."
+sidebar_order: 15
 ---
 
 For a quick reference, there is a [complete example](https://github.com/getsentry/sentry-go/tree/master/_examples/zap) at the Go SDK source code repository.
@@ -136,7 +137,3 @@ scopedLogger.Info("Processing completed")
 ```
 
 <Include name="logs/go-ctx-usage-alert.mdx"/>
-
-## Logs
-
-For comprehensive logging setup with zap, including advanced configuration options and best practices, see the [Go Logs documentation](/platforms/go/logs/). The zap integration shown above provides seamless integration with Sentry's structured logging features.

…cs/platforms/go/guides/zerolog/index.mdx docs/platforms/go/common/logs/zerolog.mdxdocs/platforms/go/guides/zerolog/index.mdx renamed to docs/platforms/go/common/logs/zerolog.mdx docs/platforms/go/guides/zerolog/index.mdx renamed to docs/platforms/go/common/logs/zerolog.mdx

@@ -1,8 +1,20 @@
 ---
 title: Zerolog
-description: "Zerolog is a fast and efficient logging library for Go, designed for structured logging. This guide demonstrates how to integrate Zerolog with Sentry."
+description: "Capture error events from Zerolog and send them to Sentry. Note: Zerolog does not support Structured Logs."
+sidebar_order: 30
 ---
 
+<Alert level="warning">
+
+The zerolog integration sends error events to Sentry but does not support Structured Logs due to architectural limitations:
+- The `io.Writer` interface lacks access to `context.Context`, preventing proper per-request hub isolation
+- In concurrent applications, breadcrumbs from different requests may leak into each other's events
+- Related issues: [#1178](https://github.com/getsentry/sentry-go/issues/1178), [#1029](https://github.com/getsentry/sentry-go/issues/1029)
+
+For Structured Logs, use our Sentry.Logger or any of the supported integrations instead.
+
+</Alert>
+
 For a complete example, visit the [Go SDK source code repository](https://github.com/getsentry/sentry-go/tree/master/_examples/zerolog).
 
 [Go Dev-style API documentation](https://pkg.go.dev/github.com/getsentry/sentry-go/zerolog) is also available.
@@ -14,8 +26,6 @@ go get github.com/getsentry/sentry-go
 go get github.com/getsentry/sentry-go/zerolog
 ```
 
-<Break />
-
 ## Configure
 
 ### Initialize the Sentry SDK
@@ -29,8 +39,8 @@ The sentryzerolog.Options struct has the following fields:
 
 ```go
 // Levels specifies the log levels that will trigger event sending to Sentry.
-// Only log messages at these levels will be sent. By default, the levels are
-// Error, Fatal, and Panic.
+// Only log messages at these levels will be sent as error events. By default,
+// the levels are Error, Fatal, and Panic.
 Levels []zerolog.Level
 
 // WithBreadcrumbs, when enabled, adds log entries as breadcrumbs in Sentry.
@@ -40,43 +50,63 @@ WithBreadcrumbs bool
 
 // FlushTimeout sets the maximum duration allowed for flushing events to Sentry.
 // This is the time limit within which all pending events must be sent to Sentry
-// before the application exits. A typical use is ensuring all logs are sent before
-// application shutdown. The default timeout is usually 3 seconds.
+// before the application exits. The default timeout is usually 3 seconds.
 FlushTimeout time.Duration
 ```
 
-## Verify
+## What Zerolog Integration Supports
+
+The zerolog integration **does** support sending **error events** to Sentry:
 
 ```go
-// Configure Zerolog to use Sentry as a writer
-sentryWriter, err := sentryzerolog.New(sentryzerolog.Config{
-	ClientOptions: sentry.ClientOptions{
+import (
+	"errors"
+	"time"
+	"os"
+
+	"github.com/getsentry/sentry-go"
+	sentryzerolog "github.com/getsentry/sentry-go/zerolog"
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+)
+
+func main() {
+	// Initialize Sentry
+	err := sentry.Init(sentry.ClientOptions{
 		Dsn: "___PUBLIC_DSN___",
-	},
-	Options: sentryzerolog.Options{
-		Levels:          []zerolog.Level{zerolog.ErrorLevel, zerolog.FatalLevel, zerolog.PanicLevel},
-		WithBreadcrumbs: true,
-		FlushTimeout:    3 * time.Second,
-	},
-})
-if err != nil {
-	log.Fatal().Err(err).Msg("failed to create sentry writer")
-}
-defer sentryWriter.Close()
+		// Note: EnableLogs is for Structured Logs, not zerolog error events
+	})
+	if err != nil {
+		log.Fatal().Err(err).Msg("sentry initialization failed")
+	}
+	defer sentry.Flush(2 * time.Second)
 
-// Use Sentry writer in Zerolog
-log.Logger = log.Output(zerolog.MultiLevelWriter(zerolog.ConsoleWriter{Out: os.Stderr}, sentryWriter))
+	// Configure Zerolog to send error events to Sentry
+	sentryWriter, err := sentryzerolog.New(sentryzerolog.Config{
+		Options: sentryzerolog.Options{
+			// These levels will be sent as error events
+			Levels:          []zerolog.Level{zerolog.ErrorLevel, zerolog.FatalLevel, zerolog.PanicLevel},
+			// Disable breadcrumbs in concurrent applications to prevent leakage
+			WithBreadcrumbs: false,
+			FlushTimeout:    3 * time.Second,
+		},
+	})
+	if err != nil {
+		log.Fatal().Err(err).Msg("failed to create sentry writer")
+	}
+	defer sentryWriter.Close()
 
-// Test logging - this will be sent to Sentry as an event
-log.Error().Msg("This error will be sent to Sentry!")
+	// Use Sentry writer in Zerolog
+	log.Logger = log.Output(zerolog.MultiLevelWriter(zerolog.ConsoleWriter{Out: os.Stderr}, sentryWriter))
 
-// Example of logging with error context
-log.Error().Err(errors.New("test error")).Msg("An error occurred")
+	// This will be sent as an error event to Sentry
+	log.Error().Msg("This is an error event, not a structured log")
+}
 ```
 
 ## Usage
 
-To integrate Sentry with Zerolog, you need to set up a custom writer that sends logs to Sentry based on the configured levels.
+To integrate Sentry with Zerolog, you need to set up a custom writer that sends error events to Sentry based on the configured levels.
 
 ```go
 import (
@@ -131,18 +161,18 @@ func main() {
 	// Log an InfoLevel entry to STDERR (not sent to Sentry)
 	log.Info().Msg("Application has started")
 
-	// Log an ErrorLevel entry to STDERR and Sentry
+	// Log an ErrorLevel entry to STDERR and send as error event to Sentry
 	log.Error().Msg("oh no!")
 
-	// Log a FatalLevel entry to STDERR, send to Sentry, and terminate the application
+	// Log a FatalLevel entry to STDERR, send as error event to Sentry, and terminate the application
 	log.Fatal().Err(errors.New("can't continue")).Msg("fatal error occurred")
 }
 ```
 
 
 ### Using `hubProvider` for Scoped Sentry Hubs
 
-The hubProvider allows you to configure the Sentry hook to use a custom Sentry hub. This can be particularly useful when you want to scope logs to specific goroutines or operations, enabling more precise grouping and context in Sentry.
+The hubProvider allows you to configure the Sentry hook to use a custom Sentry hub. This can be particularly useful when you want to scope error events to specific goroutines or operations, enabling more precise grouping and context in Sentry.
 
 You can set a custom hubProvider function using the SetHubProvider method:
 
@@ -153,13 +183,13 @@ sentryHook.SetHubProvider(func() *sentry.Hub {
 })
 ```
 
-This ensures that logs from specific contexts or threads use the appropriate Sentry hub and scope.
+This ensures that error events from specific contexts or threads use the appropriate Sentry hub and scope.
 
 
-Use Zerolog as you normally would, and it will automatically send logs at or above the specified levels to Sentry.
+Use Zerolog as you normally would, and it will automatically send error events at or above the specified levels to Sentry.
 
 Note: Ensure Sentry is flushed before the application exits to avoid losing any pending events.
 
-## Next Steps
+## Concurrent Applications
 
-- Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup
+For concurrent applications (HTTP/gRPC servers), use scoped hubs to link error events to traces. See the `hubProvider` section above and the <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> documentation for best practices on proper hub management.

docs/platforms/go/common/tracing/index.mdx

@@ -34,7 +34,9 @@ Learn more about tracing <PlatformLink to="/configuration/options/#tracing-optio
 
 ## Verify
 
-Test out tracing by starting and finishing a transaction, which you _must_ do so transactions can be sent to Sentry. Learn how in our <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> content.
+If you're using an HTTP framework with Sentry middleware (Gin, Echo, Fiber, etc.), transactions are created automatically for every incoming request. See <PlatformLink to="/tracing/instrumentation/auto-instrumentation/">Automatic Instrumentation</PlatformLink> for details.
+
+If you're not using a supported framework, you can manually create transactions. Learn how in our <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> content.
 
 While you're testing, set <PlatformIdentifier name="traces-sample-rate" /> to `1.0`, as that ensures that every transaction will be sent to Sentry. Once testing is complete, you may want to set a lower <PlatformIdentifier name="traces-sample-rate" /> value, or switch to using <PlatformIdentifier name="traces-sampler" /> to selectively sample and filter your transactions, based on contextual data.
 

docs/platforms/go/common/tracing/instrumentation/auto-instrumentation.mdx

@@ -0,0 +1,35 @@
+---
+title: Automatic Instrumentation
+description: "Learn what gets captured automatically when using Sentry's HTTP framework middleware."
+sidebar_order: 10
+---
+
+If you're using one of Sentry's HTTP framework middlewares, transactions are created automatically for all incoming HTTP requests when tracing is enabled. No additional code is needed beyond the middleware setup.
+
+## What Gets Captured
+
+<PlatformContent includePath="tracing/automatic-instrumentation/http-frameworks" />
+
+## Supported Frameworks
+
+Sentry provides middleware for the following Go HTTP frameworks:
+
+| Framework | Package | Guide |
+|-----------|---------|-------|
+| Gin | `sentry-go/gin` | [Gin guide](/platforms/go/guides/gin/) |
+| Echo | `sentry-go/echo` | [Echo guide](/platforms/go/guides/echo/) |
+| Fiber | `sentry-go/fiber` | [Fiber guide](/platforms/go/guides/fiber/) |
+| net/http | `sentry-go/http` | [net/http guide](/platforms/go/guides/http/) |
+| Iris | `sentry-go/iris` | [Iris guide](/platforms/go/guides/iris/) |
+| FastHTTP | `sentry-go/fasthttp` | [FastHTTP guide](/platforms/go/guides/fasthttp/) |
+| Negroni | `sentry-go/negroni` | [Negroni guide](/platforms/go/guides/negroni/) |
+
+Each middleware is installed and configured as part of the framework setup. See the individual guide pages for installation instructions.
+
+## HTTP Client Spans
+
+For outbound HTTP requests, use the `sentryhttpclient` package to automatically create spans for client requests. See the <PlatformLink to="/tracing/instrumentation/custom-instrumentation/requests-module/">HTTP Requests</PlatformLink> documentation for details.
+
+## Adding Custom Spans
+
+Once the middleware creates a transaction, you can add child spans within your handlers to track specific operations. See <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> for details.