Skip to content

Commit ce5ec87

Browse files
devin-ai-integration[bot]xinlili-statsigtore-statsig
authored
Add process forking warning to Python Core SDK documentation (#3184)
* Add process forking warning to Python Core SDK documentation - Add comprehensive warning about not forking processes after Statsig initialization - Include technical explanation of threading/async runtime issues - Provide correct examples for uWSGI and Gunicorn deployment scenarios - Show incorrect initialization pattern to avoid - Offer lazy initialization as alternative solution - Addresses potential deadlock scenarios in production WSGI deployments Co-Authored-By: xin@statsig.com <xin@statsig.com> * Fix spellcheck: Add 'Gunicorn' to dictionary - Resolves spellcheck CI failure for Python Core SDK documentation - Gunicorn is a legitimate Python WSGI HTTP Server name used in examples Co-Authored-By: xin@statsig.com <xin@statsig.com> * Update _faqs.mdx --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: xin@statsig.com <xin@statsig.com> Co-authored-by: tore-statsig <74584483+tore-statsig@users.noreply.github.com>
1 parent 068d598 commit ce5ec87

File tree

2 files changed

+73
-0
lines changed

2 files changed

+73
-0
lines changed

cspell.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
"GDPR",
7777
"Github",
7878
"GTM",
79+
"Gunicorn",
7980
"IAM",
8081
"IDSync",
8182
"IDFA",

docs/server-core/python/_faqs.mdx

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
## Process Forking and WSGI Servers
2+
3+
### ⚠️ Warning: Do not fork processes after Statsig initialization
4+
5+
**Important:** Never fork processes after calling `statsig.initialize()`. Doing so will put Statsig in a weird state and may cause deadlocks.
6+
7+
The Python Core SDK uses internal threading and async runtime components that do not work correctly when copied across process boundaries. When a process forks after initialization, these components can become corrupted, leading to:
8+
9+
- Deadlocks in event logging
10+
- Hanging initialization calls
11+
- Unpredictable SDK behavior
12+
- Silent failures in feature evaluation
13+
14+
### Correct initialization for WSGI servers
15+
16+
For production deployments using WSGI servers like uWSGI or Gunicorn, ensure Statsig is initialized **after** the worker processes are forked, not in the main process.
17+
18+
#### ✅ Correct: uWSGI example
19+
20+
```python
21+
# app.py
22+
from statsig_python_core import Statsig, StatsigOptions
23+
from flask import Flask
24+
25+
app = Flask(__name__)
26+
statsig = None
27+
28+
def init_statsig():
29+
global statsig
30+
if statsig is None:
31+
options = StatsigOptions()
32+
options.environment = "production"
33+
statsig = Statsig("your-server-secret-key", options)
34+
statsig.initialize().wait()
35+
36+
# Initialize in each worker process
37+
@app.before_first_request
38+
def before_first_request():
39+
init_statsig()
40+
41+
@app.route('/')
42+
def index():
43+
# Use statsig here
44+
return "Hello World"
45+
```
46+
47+
```ini
48+
# uwsgi.ini
49+
[uwsgi]
50+
module = app:app
51+
master = true
52+
processes = 4
53+
# Statsig will be initialized in each worker process
54+
```
55+
56+
#### ✅ Correct: Gunicorn example
57+
58+
```python
59+
# gunicorn_config.py
60+
def post_fork(server, worker):
61+
# Initialize Statsig after worker process is forked
62+
from app import init_statsig
63+
init_statsig()
64+
65+
# app.py - same as uWSGI example above
66+
```
67+
68+
```bash
69+
# Start Gunicorn with post-fork hook
70+
gunicorn --config gunicorn_config.py app:app
71+
```
72+

0 commit comments

Comments
 (0)