docs: enhance troubleshooting for Gunicorn/Uvicorn worker spans#2555
docs: enhance troubleshooting for Gunicorn/Uvicorn worker spans#2555adionit7 wants to merge 3 commits intoSigNoz:mainfrom
Conversation
adionit7
requested review from
makeavish,
pranay01 and
therealpandey
as code owners
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
- Add detailed explanation of forking issue with multi-worker servers - Include gunicorn_config.py example with post_fork hook - Link to FastAPI production example for complete reference - Add link to OpenTelemetry multiprocessing docs
adionit7
force-pushed
the
docs/python-gunicorn-worker-troubleshooting
branch
from
345f1ae to
56e4c90
Compare
shubham-signoz
left a comment
shubham-signoz
left a comment
There was a problem hiding this comment.
Hey, thanks for taking the time to improve the docs here!
A couple of things though - the post_fork example won't quite work as written. opentelemetry-bootstrap -a install is actually a package installer so calling it at runtime on every worker fork isn't what we want or the right way to do it. (With 4 workers you'd have 4 pip install attempts on startup, and more each time workers recycle. In most production setups this just fails (read-only containers, no network, slim images without pip). And even if it ran, it's not a reliable fix since it might work for some setups but not others - the packages are already there, it's the SDK state (TracerProvider, exporters, processors) that didn't survive the fork).
The correct approach is reinitialising the TracerProvider/MeterProvider in each worker.We do already cover this in the #running-with-gunicorn-or-uwsgi section with links to the official post_fork examples.
That said - I'm curious what prompted this. Was something confusing about the existing pre-fork/post-fork explanation? Would love to hear what tripped you up so we can fix it in the right place.
Removes the opentelemetry-bootstrap --action=install example which is incorrect for post_fork (it's a package installer, not runtime initialization). Instead points to the existing #running-with-gunicorn section and official OTel Python post_fork examples.
Thanks for the catch, Shubham! You are right.. running What tripped me up: I was specifically looking for a 'Troubleshooting' section for missing spans and completely missed the Updates pushed:
(Note: I also updated my PR in the examples repo to reflect the correct post_fork approach). Ready for re-review! |
@adionit7 I think the existing troubleshooting already has a reference for the gunicorn preload. I don't think we need any more additional information except on this line. Do you think maybe we need to make this line more explicit about the issue? |
|
@shubham-signoz That makes total sense! I agree.. keeping it concise is better. The current line (need extra config) is a bit passive, which is why I scrolled past it. I'll update it to explicitly mention 'missing spans' and 'forking issues'. That way, anyone debugging dropped traces will immediately know this is the relevant section. Updating the PR now to just modify this line. |
Removed verbose troubleshooting section. Instead, explicitly mention 'missing spans' and 'forking issues' in the existing Gunicorn/uWSGI section so users searching for these terms find the fix immediately.
2 participants
Pull Request
📄 Summary
Users deploying FastAPI/Python apps with Gunicorn or Uvicorn multiple workers often experience missing spans in SigNoz. The existing troubleshooting section mentions this briefly but doesn't explain the root cause or provide a concrete solution.
This PR enhances the troubleshooting section with:
gunicorn_config.pyexample withpost_forkhookThis helps users understand the problem and implement the fix themselves, reducing support load.
✅ Change Type
Select all that apply
🐛 Bug Context
N/A - Documentation enhancement.
🧪 Testing Strategy
📝 Changelog
📋 Checklist
👀 Notes for Reviewers
This addresses the issue mentioned in the tweet thread where users struggle with Gunicorn workers dropping spans. The existing troubleshooting section was too brief - this adds the detailed explanation and working code example that users need.
The
gunicorn_config.pyexample matches the pattern used in the FastAPI production example we added to the examples repo, ensuring consistency across documentation.