From 1e18ba970c3d6d7cfd268b60c7c4422582c20a2f Mon Sep 17 00:00:00 2001
From: Daniel Szoke <daniel.szoke@sentry.io>
Date: Tue, 27 Aug 2024 14:39:57 +0200
Subject: [PATCH] docs(python): Document sys.exit integration

Add documentation for the sys.exit integration, introduced in https://github.com/getsentry/sentry-python/pull/3401.

Closes #11043
---
 docs/platforms/python/integrations/index.mdx  |  1 +
 .../python/integrations/sys_exit/index.mdx    | 72 +++++++++++++++++++
 2 files changed, 73 insertions(+)
 create mode 100644 docs/platforms/python/integrations/sys_exit/index.mdx

diff --git a/docs/platforms/python/integrations/index.mdx b/docs/platforms/python/integrations/index.mdx
index 2668d46ccf8bc..8bbc83947c8e1 100644
--- a/docs/platforms/python/integrations/index.mdx
+++ b/docs/platforms/python/integrations/index.mdx
@@ -110,6 +110,7 @@ The Sentry SDK uses integrations to hook into the functionality of popular libra
 | <LinkWithPlatformIcon platform="python.pure_eval"     label="Enhanced Locals" url="/platforms/python/integrations/pure_eval" />     |                  |
 | <LinkWithPlatformIcon platform="python.gnu_backtrace" label="GNU Backtrace"   url="/platforms/python/integrations/gnu_backtrace" /> |                  |
 | <LinkWithPlatformIcon platform="python.socket"        label="Socket"          url="/platforms/python/integrations/socket" />        |                  |
+| <LinkWithPlatformIcon platform="python.sys_exit"      label="sys.exit"        url="/platforms/python/integrations/sys_exit" />      |                  |
 | <LinkWithPlatformIcon platform="python.tryton"        label="Tryton"          url="/platforms/python/integrations/tryton" />        |                  |
 | <LinkWithPlatformIcon platform="python.wsgi"          label="WSGI"            url="/platforms/python/integrations/wsgi" />          |                  |
 
diff --git a/docs/platforms/python/integrations/sys_exit/index.mdx b/docs/platforms/python/integrations/sys_exit/index.mdx
new file mode 100644
index 0000000000000..229101cacb252
--- /dev/null
+++ b/docs/platforms/python/integrations/sys_exit/index.mdx
@@ -0,0 +1,72 @@
+---
+title: sys.exit
+description: Learn how to use Sentry to capture sys.exit calls
+---
+
+The `SysExitIntegration` records `sys.exit` calls by capturing the `SystemExit` exception raised by `sys.exit`.
+
+## Install
+
+```bash
+pip install --upgrade "sentry-sdk"
+```
+
+## Configure
+
+The `SysExitIntegration` is disabled by default, and the SDK only captures `SystemExit` exceptions automatically if this integration is manually enabled.
+
+To enable the `SysExitIntegration` and configure it to only capture unsuccessful `sys.exit` calls, use the following:
+
+<SignInNote />
+
+```python
+import sentry_sdk
+from sentry_sdk.integrations.sys_exit import SysExitIntegration
+
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    integrations=[SysExitIntegration()],
+)
+```
+
+If you wish to capture successful and unsuccessful `sys.exit` calls, use the following, instead:
+
+```python
+import sentry_sdk
+from sentry_sdk.integrations.sys_exit import SysExitIntegration
+
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    integrations=[SysExitIntegration(capture_successful_exits=True)],
+)
+```
+
+A `sys.exit` call is considered "successful" when the function is passed a value of `0` or `None`. Passing any other value results in an "unsuccessful" exit.
+
+
+## Verify
+
+Running the following snippet should result in a `SystemExit` exception being reported to Sentry.
+
+```python
+import sys
+
+import sentry_sdk
+from sentry_sdk.integrations.sys_exit import SysExitIntegration
+
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    integrations=[SysExitIntegration()],
+)
+
+sys.exit(1)
+```
+
+If you use `capture_successful_exits=True`, calling `sys.exit(0)` should also report a `SystemExit` exception to Sentry.
+
+
+<Alert level="info" title="Manually-raised SystemExit">
+
+Please note that the `SysExitIntegration` only captures `SystemExit` exceptions which are raised by calling `sys.exit`. If your code raises `SystemExit` without calling `sys.exit`, the exception will not be reported to Sentry.
+
+</Alert>