From ce7e047d27d3ac2cd3816e3837871e9018b9ea16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kamil=20Og=C3=B3rek?= <kamil.ogorek@gmail.com>
Date: Mon, 1 Jul 2019 14:20:12 +0200
Subject: [PATCH] docs: Create documentation for scopes usage inside Goroutines

---
 __tests__/__snapshots__/documentation.js.snap |  1 +
 .../_documentation/platforms/go/goroutines.md | 53 +++++++++++++++++++
 .../_documentation/platforms/go/index.md      |  1 +
 .../platforms/go/integrations.md              |  2 +-
 4 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 src/collections/_documentation/platforms/go/goroutines.md

diff --git a/__tests__/__snapshots__/documentation.js.snap b/__tests__/__snapshots__/documentation.js.snap
index c4e0d683b52b1..3329333c5feee 100644
--- a/__tests__/__snapshots__/documentation.js.snap
+++ b/__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",
diff --git a/src/collections/_documentation/platforms/go/goroutines.md b/src/collections/_documentation/platforms/go/goroutines.md
new file mode 100644
index 0000000000000..69ce2625c798c
--- /dev/null
+++ b/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")
+}()
+```
\ No newline at end of file
diff --git a/src/collections/_documentation/platforms/go/index.md b/src/collections/_documentation/platforms/go/index.md
index 9c1e32ed53759..8d5e788b41332 100644
--- a/src/collections/_documentation/platforms/go/index.md
+++ b/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 -%})
diff --git a/src/collections/_documentation/platforms/go/integrations.md b/src/collections/_documentation/platforms/go/integrations.md
index 776f0d11db555..1dc2a1a00a8fd 100644
--- a/src/collections/_documentation/platforms/go/integrations.md
+++ b/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.