docs: Create documentation for scopes usage inside Goroutines

__tests__/__snapshots__/documentation.js.snap

@@ -276,6 +276,7 @@ Array [
  "platforms/go/config/index.html",
  "platforms/go/echo/index.html",
  "platforms/go/gin/index.html",
+ "platforms/go/goroutines/index.html",
  "platforms/go/http/index.html",
  "platforms/go/index.html",
  "platforms/go/integrations/index.html",

src/collections/_documentation/platforms/go/goroutines.md

@@ -0,0 +1,53 @@
+---
+title: Goroutines
+sidebar_order: 4
+---
+
+A goroutine is a lightweight thread managed by the Go runtime. It is run concurrently with other functions in your code. And because of this, it has to keep track of it's own data locally. Otherwise, there is a chance that you will override your informations stored in the Scope. More on this in [Scopes and Hubs]({%- link _documentation/enriching-error-data/scopes.md -%}?platform={{ include.platform }}) section.
+
+The easiest way to handle this, is to create a new `Hub`, however this would require you to rebind the current `Client` and handle `Scope` yourself. That is why we provide a helper method called `Clone`. It takes care of creating a `Hub`, cloning existing `Scope` and reassigning it alongside `Client` to newly create instance.
+
+Once cloned, `Hub` is completly isolated and can be used safely inside concurrent call. However, instead of using globally exposed methods, they should be called directly on the `Hub`.
+
+Here are two examples, one that is non-deterministic, would leak information between threads and could trigger a concurrent-write panic and one that is totally safe, and should be used instead.
+
+```go
+// Example of __INCORRECT__ use of scopes inside a Goroutines - DON'T USE IT!
+
+go func() {
+ sentry.ConfigureScope(func(scope *sentry.Scope) {
+ scope.SetTag("secretTag", "go#1")
+ })
+ sentry.CaptureMessage("Hello from Goroutine! #1")
+}()
+
+go func() {
+ sentry.ConfigureScope(func(scope *sentry.Scope) {
+ scope.SetTag("secretTag", "go#2")
+ })
+ sentry.CaptureMessage("Hello from Goroutine! #2")
+}()
+
+// at this point both events can have either `go#1` tag or `go#2` tag or it can panic with concurrent writes. We'll never know.
+```
+
+```go
+// Example of __CORRECT__ use of scopes inside a Goroutines
+
+go func(localHub *sentry.Hub) {
+ // as goroutine argument
+ localHub.ConfigureScope(func(scope *sentry.Scope) {
+ scope.SetTag("secretTag", "go#1")
+ })
+ localHub.CaptureMessage("Hello from Goroutine! #1")
+}(sentry.CurrentHub().Clone())
+
+go func() {
+ // or created locally
+ localHub := sentry.CurrentHub().Clone()
+ localHub.ConfigureScope(func(scope *sentry.Scope) {
+ scope.SetTag("secretTag", "go#2")
+ })
+ localHub.CaptureMessage("Hello from Goroutine! #2")
+}()
+```

src/collections/_documentation/platforms/go/index.md

@@ -91,6 +91,7 @@ For more detailed information about how to get the most out of `sentry-go` there
 - [Error Reporting]({%- link _documentation/error-reporting/quickstart.md -%}?platform={{ include.platform }})
 - [Enriching Error Data]({%- link _documentation/enriching-error-data/context.md -%}?platform={{ include.platform }})
 - [Transports]({%- link _documentation/platforms/go/transports.md -%})
+- [Goroutines]({%- link _documentation/platforms/go/goroutines.md -%})
 - [Integrations]({%- link _documentation/platforms/go/integrations.md -%})
  - [net/http]({%- link _documentation/platforms/go/http.md -%})
  - [echo]({%- link _documentation/platforms/go/echo.md -%})

src/collections/_documentation/platforms/go/integrations.md

@@ -1,6 +1,6 @@
 ---
 title: Integrations
-sidebar_order: 4
+sidebar_order: 5
 ---
 
 The sentry-go package currently comes with an integration for the native `net/http` package, `echo`, `gin`, `iris`, `martini` and `negroni` to make it easy to handle common scenarios.