You wired your LLM app to send traces to PostHog. The SDK returned HTTP 200. And the dashboard is still empty. Nothing errored, nothing arrived. That silence is the worst failure mode in observability — and it is exactly the gap LLM Doctor closes.
What it does
doctor check sends one controlled OpenTelemetry test span to PostHog, reads it back through the API, and tells you the exact failure mode — one of ten named modes — with a plain-English fix. It refuses to claim your pipeline is healthy off an unconfirmed 2xx: accepted and actually ingested are different facts, and it verifies the second one.
The mode that motivated the whole tool: OpenInference-shaped spans (Arize, LlamaIndex) are accepted with HTTP 2xx but never classified as LLM generations. Everything looks fine. Nothing shows up. LLM Doctor names it and tells you what to change.
doctor fix goes one step further — a local OTLP receiver that repairs spans in flight: it remaps llm.* attributes to gen_ai.* and injects a missing gen_ai.operation.name, preserving trace IDs. Your instrumentation stays untouched; the traffic gets healed on the way through.
Why I built it
I lost hours to that empty dashboard, and the debugging loop was miserable: change a config value, redeploy, squint at the dashboard, repeat. A diagnostic should do that loop for you, once, deterministically, and then say what is wrong in words a human can act on. So I wrote one.
Get it
pip install posthog-llm-doctor — Python 3.11+, MIT license. Source on GitHub, package on PyPI.