Revise Shutdown and Draining section (#1512)

Co-Authored-By: Kamil Ogórek <[email protected]>
Co-Authored-By: Tien "Mimi" Nguyen <[email protected]>

Author: 3 people

src/collections/_documentation/error-reporting/configuration/drain-example/go.md

@@ -1,11 +1,18 @@
-The client provides a `Flush` method that takes the time in `time.Duration` for how long it waits and will return a boolean that indicates whether everything was flushed or the timeout kicked in.
+To avoid unintentionally dropping events when the program terminates, arrange
+for `sentry.Flush` to be called, typically using `defer`.
+
+If you use multiple clients, arrange for each of them to be flushed as
+appropriate.
+
+`Flush` waits until any buffered events are sent to the Sentry server, blocking
+for at most the given timeout. It returns `false` if the timeout was reached. In
+that case, some events may not have been sent.
 
 ```go
-sentry.CaptureMessage("my message")
+func main() {
+	// err := sentry.Init(...)
+	defer sentry.Flush(2 * time.Second)
 
-if sentry.Flush(time.Second * 2) {
-	fmt.Println("All queued events delivered!")
-} else {
-	fmt.Println("Flush timeout reached")
+	sentry.CaptureMessage("my message")
 }
 ```

src/collections/_documentation/error-reporting/configuration/drain-example/javascript.md

@@ -1,12 +1,15 @@
-The client provides a close method that optionally takes the time in milliseconds for how long it
-waits and will return a promise that resolves when everything was flushed or the timeout kicked
+The `close` method optionally takes a timeout in milliseconds and returns a
+promise that resolves when all pending events are flushed, or the timeout kicks
 in.
 
 ```javascript
-const client = Sentry.getCurrentHub().getClient();
-if (client) {
-  client.close(2000).then(function() {
-    process.exit();
-  });
-}
+Sentry.close(2000).then(function() {
+  process.exit();
+});
 ```
+
+After a call to `close`, the current client cannot be used anymore. It's
+important to only call `close` immediately before shutting down the application.
+
+Alternatively, the `flush` method drains the event queue while keeping the
+client enabled for continued use.

src/collections/_documentation/error-reporting/configuration/drain-example/native.md

@@ -6,3 +6,6 @@ sentry_shutdown();
 
 Calling `sentry_shutdown()` before exiting the application is critical to avoid
 data loss.
+
+After shutdown, the client cannot be used anymore. It's important to only call
+`sentry_shutdown()` immediately before shutting down the application.

src/collections/_documentation/error-reporting/configuration/drain-example/python.md

@@ -8,3 +8,9 @@ client = Hub.current.client
 if client is not None:
     client.close(timeout=2.0)
 ```
+
+After a call to `close`, the client cannot be used anymore. It's important to
+only call `close` immediately before shutting down the application.
+
+Alternatively, the `flush` method drains the event queue while keeping the
+client enabled for continued use.

src/collections/_documentation/error-reporting/configuration/drain-example/rust.md

@@ -2,11 +2,14 @@ When the Rust SDK initializes a guard is returned from the `init` function.  The
 will automatically wait `shutdown_timeout` seconds.  This means you just need to hold on to
 the guard and make sure it disposes on shutdown.  Alternatively the client can be closed:
 
-```javascript
+```rust
 use std::time::Duration;
 use sentry::Hub;
 
 if let Some(client) = Hub.current().client() {
     client.close(Some(Duration::from_secs(2)));
 }
 ```
+
+After a call to `close`, the client cannot be used anymore. It's important to
+only call `close` immediately before shutting down the application.

src/collections/_documentation/error-reporting/configuration/draining.md

@@ -3,15 +3,9 @@ title: 'Shutdown and Draining'
 sidebar_order: 1
 ---
 
-Most SDKs use a background queue to send out events.  Because the queue sends asynchronously in the background
-it means that some events might be lost if the application shuts down unexpectedly.  To prevent this all SDKs
-provide mechanisms to cope with this.
-
-Typically SDKs provide two ways to shut down: a controlled shutdown where the system will wait up to about two
-seconds to flush out events (configurable) and an uncontrolled shutdown (also referred to as "killing" the
-client).
+The default behavior of most SDKs is to send out events over the network
+asynchronously in the background. This means that some events might be lost if
+the application shuts down unexpectedly. The SDKs provide mechanisms to cope
+with this.
 
 {% include components/platform_content.html content_dir='drain-example' %}
-
-After shutdown the client cannot be used any more so make sure to only do that right before you shut down
-the application.