docs(python): document distributed tracing

[turnipdabeets]

Changes

posthog for Python gains a native span API, with no OpenTelemetry dependency, in the traces stack ending at PostHog/posthog-python#957. This documents it, mirroring the Node.js docs from #19837 and #20109.

• Python library page – new ## Distributed tracing section: enabling traces, start_span as a with block or manual span, attributes and the span API, traceparent propagation, the person/session join, before_span_send, span limits, configuration, and flushing. tracing: true adds Python to the Tracing column on /docs/libraries.
• /docs/distributed-tracing/installation/python – now offers two routes like the Node.js guide: posthog first, then the existing OpenTelemetry steps, plus how to set the person/session attributes yourself with OpenTelemetry.
• Install index, start-here, and the /docs/distributed-tracing landing page – "On Node.js" becomes "On Node.js and Python", linking both guides.
• Serverless section of the Python page notes that sync_mode doesn't cover spans.

AsyncPosthog has no span API yet, so the docs say so and point async users to OpenTelemetry.

Merge after posthog 7.58.0 is on PyPI. The tracing stack is merged to posthog-python main, and its minor changeset is the only one pending. 7.57.0 shipped earlier the same day without tracing, so the pages say 7.58.0. The release workflow for the merge is queued.

Every snippet was run against the stack tip, with a local server capturing the OTLP payload. Behavioral claims were checked against the SDK source.

Companions: PostHog/posthog#102724 (tracing empty state) and PostHog/context-mill#399 (tracing skill).

Checklist

• I've read the docs and/or content style guides.
• Words are spelled using American English
• Use relative URLs for internal links
• I've checked the pages added or changed in the Vercel preview build (the Cloudflare Pages preview: all five changed pages render, and Python shows tracing: true in the /docs/libraries data)
• If I moved a page, I added a redirect in vercel.json (no pages moved)

🤖 Generated with Claude Code

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Sep 19, 2026 06:40PM

Changed pages

Page	Source
Install tracing	contents/docs/distributed-tracing/installation/index.mdx
Python tracing installation	contents/docs/distributed-tracing/installation/python.mdx
Getting started with distributed tracing	contents/docs/distributed-tracing/start-here.mdx
Python	contents/docs/libraries/python/index.mdx

[github-actions]

Vale prose linter → found 0 errors, 37 warnings, 1 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/distributed-tracing/installation/python.mdx — 0 errors, 1 warnings, 0 suggestions

Line	Severity	Message	Rule
124:4	warning	'With OpenTelemetry' heading should be in sentence case, and product names should be capitalized.	PostHogBase.SentenceCase

contents/docs/distributed-tracing/start-here.mdx — 0 errors, 1 warnings, 0 suggestions

Line	Severity	Message	Rule
77:21	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	PostHogBase.ProductNames

contents/docs/libraries/python/index.mdx — 0 errors, 35 warnings, 1 suggestions

Line	Severity	Message	Rule
6:18	warning	Use 'GitHub' instead of 'github'.	Vale.Terms
6:37	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
21:25	warning	Avoid trivializing words. 'easy to' can sound dismissive to the reader.	PostHogDocs.Trivializers
21:58	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
31:12	warning	'asyncio' is a possible misspelling.	PostHogBase.Spelling
33:28	warning	'asyncio' is a possible misspelling.	PostHogBase.Spelling
33:135	warning	'asyncio' is a possible misspelling.	PostHogBase.Spelling
84:14	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
86:81	warning	'accessors' is a possible misspelling.	PostHogBase.Spelling
102:90	warning	'accessors' is a possible misspelling.	PostHogBase.Spelling
106:43	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
150:232	warning	'personless' is a possible misspelling.	PostHogBase.Spelling
202:4	warning	'Feature flags' heading should be in sentence case, and product names should be capitalized.	PostHogBase.SentenceCase
202:4	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept.	PostHogBase.ProductNames
204:189	warning	'accessors' is a possible misspelling.	PostHogBase.Spelling
228:8	warning	Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept.	PostHogBase.ProductNames
228:55	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
228:128	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
240:28	warning	Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept.	PostHogBase.ProductNames
240:54	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
246:4	warning	'Error tracking' heading should be in sentence case, and product names should be capitalized.	PostHogBase.SentenceCase
246:4	warning	Capitalize 'Error Tracking' for PostHog's product. Use 'Error tracking' for the general industry concept.	PostHogBase.ProductNames
329:8	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
340:134	warning	'asyncio' is a possible misspelling.	PostHogBase.Spelling
506:274	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
508:7	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
534:62	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
534:100	warning	Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept.	PostHogBase.ProductNames
536:117	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	PostHogBase.ProductNames
557:5	warning	'Enable TCP keepalive' heading should be in sentence case, and product names should be capitalized.	PostHogBase.SentenceCase
557:16	warning	'keepalive' is a possible misspelling.	PostHogBase.Spelling
559:5	warning	'keepalive' is a possible misspelling.	PostHogBase.Spelling
567:18	warning	'keepalive' is a possible misspelling.	PostHogBase.Spelling
624:47	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	PostHogBase.ProductNames
634:4	warning	'Serverless environments (Render/Lambda/...)' heading should be in sentence case, and product names should be capitalized.	PostHogBase.SentenceCase
645:5	warning	'Asyncio' is a possible misspelling.	PostHogBase.Spelling

[github-actions]

Bundle report

Total JS (gzip)

8.66 MiB (+0.3 KiB / +0.0%)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint	Eager size	Budget	Modules
✅ app	18.62 MiB (+2.3 KiB / +0.0%)	report-only	2069

Largest modules in the app closure

Module	Size
./src/data/mcp-tools.json	1166.5 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css	772.8 KiB
./src/components/Stickers/Stickers.tsx	696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js	481.4 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs	480.8 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules	395.1 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs	385.7 KiB
./src/hooks/useCustomers.tsx + 55 modules	372.5 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js	354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules	351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 127 modules	310.4 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js	281.9 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs	281.7 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/director.mjs	275.6 KiB
./src/components/SearchUI/index.tsx + 87 modules	273.7 KiB

---

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

[dustinbyrne]

Looks good with the non-blocking inline note. Source-reviewed with AI assistance and existing CI evidence; no new tests executed.