Skip to content

docs(node): document distributed tracing - #19837

Draft
turnipdabeets wants to merge 11 commits into
masterfrom
docs/node-distributed-tracing
Draft

docs(node): document distributed tracing#19837
turnipdabeets wants to merge 11 commits into
masterfrom
docs/node-distributed-tracing

Conversation

@turnipdabeets

@turnipdabeets turnipdabeets commented Aug 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Changes

Documents the distributed tracing API added in PostHog/posthog-js#4579.

Node.js library page — a new ## Distributed tracing section, placed after the Express request-context section it builds on:

  • The traces client option (tracing is off until it is set, no OpenTelemetry dependency)
  • withSpan for scoped spans, startSpan for detached ones, getActiveSpan
  • Span names, attributes, events, status, and kind
  • Continuing and propagating a trace with W3C traceparent
  • The person/session join — spans in a request context carry posthogDistinctId and sessionId
  • Config table, shutdown() behavior, and the edge-runtime await caveat

Distributed tracing product docs — the installation guides told Node users to install six @opentelemetry/* packages, and installation/index.mdx and start-here.mdx both stated that no PostHog-specific packages are required. That is no longer true on Node:

  • installation/nodejs.mdx now opens with a comparison of the two routes and covers posthog-node before the existing OpenTelemetry steps. Verification and next steps moved into a shared closing block so both routes end in the same place.
  • installation/nextjs.mdx keeps its OpenTelemetry steps and gains one note: server-side code can use the Node span API instead, and spans are server-side only. Tutorial: how to build a site app #4579 scopes tracing to posthog-node, so this page claims no more than that.
  • installation/index.mdx and start-here.mdx point at the Node guide for the SDK-native route, and the section is retitled from "Install OpenTelemetry tracing" to "Install tracing" in the page frontmatter and src/navs/index.js.

Feature comparison — tracing: true in the Node page's features: frontmatter and a Tracing column in src/components/LibraryComparison/index.tsx, which is what renders the table on /docs/libraries.

⚠️ Blocked on the SDK PR

Do not merge until PostHog/posthog-js#4579 has merged and shipped. Nothing on these pages exists in a released posthog-node yet.

The version in > Requires posthog-node version >= 5.52.0. (and the same floor on the two tracing install pages) is a guess — current released version is 5.51.4 and the changeset is a minor. Update it to whatever actually ships.

Notes for reviewers

  • The OpenTelemetry route stays on every page. posthog-node's span API is manual-only — extensions/express.ts creates no spans — so OTel remains the only path to auto-instrumentation, and it's what the other seven language guides teach.
  • @posthog/next would work transitively (getPostHog() returns IPostHog, options passes traces through, and the request-scoped proxy applies withContext), but nothing in packages/next tests it and Tutorial: how to build a site app #4579 doesn't claim it, so the Next.js page only points at the Node guide.
  • Worth knowing for a follow-up: scheduleDebouncedFlush fires from enqueue, so a serverless request that creates spans but captures no events gets no waitUntil flush and must call flush() itself.

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
  • If I moved a page, I added a redirect in vercel.json

@turnipdabeets
docs(node): document distributed tracing
dc5b365 
Covers withSpan/startSpan/getActiveSpan, the traces option, W3C trace
context propagation, and the person/session join.
@github-actions github-actions Bot added docs Improvements or additions to product documentation, "Docs" content PR only touches files under contents/ labels Aug 31, 2026
@turnipdabeets turnipdabeets mentioned this pull request Aug 31, 2026
Open
23 tasks
@github-actions

github-actions Bot commented Aug 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Sep 04, 2026 09:23PM

@github-actions

github-actions Bot commented Aug 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Vale prose linter → found 13 errors, 37 warnings, 3 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/nextjs.mdx — 3 errors, 1 warnings, 0 suggestions
Line Severity Message Rule
38:52 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
38:57 warning Use 'X' instead of 'x'. Vale.Terms
38:193 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
142:135 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
contents/docs/distributed-tracing/installation/nodejs.mdx — 0 errors, 3 warnings, 0 suggestions
Line Severity Message Rule
3:15 warning 'nodejs' is a possible misspelling. PostHogBase.Spelling
60:68 warning Use the Oxford comma before 'and' or 'or' in a list of three or more items. PostHogBase.OxfordComma
118: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/node/index.mdx — 10 errors, 32 warnings, 3 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
7:15 warning 'nodejs' is a possible misspelling. PostHogBase.Spelling
19:416 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
40:131 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
40:210 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
40:258 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
41:81 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
43:62 warning 'deduplicates' is a possible misspelling. PostHogBase.Spelling
44:97 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
46:80 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
145:33 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
270:4 warning 'Add request context to Express' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
309:19 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
324:107 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
328:27 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
328:267 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
343:19 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
364:186 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
380:54 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
380:175 warning 'bigints' is a possible misspelling. PostHogBase.Spelling
436:157 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
448:41 warning Avoid trivializing words. 'simply' can sound dismissive to the reader. PostHogDocs.Trivializers
472:62 warning 'unscrubbed' is a possible misspelling. PostHogBase.Spelling
479:227 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
506:154 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
523:4 warning Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept. PostHogBase.ProductNames
523:4 warning 'Feature flags' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
552:16 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
554:68 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
568:8 warning Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept. PostHogBase.ProductNames
568:55 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
579:28 warning Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept. PostHogBase.ProductNames
579:54 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
616:274 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
660:62 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
660:100 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
662:98 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
716:4 warning Capitalize 'Error Tracking' for PostHog's product. Use 'Error tracking' for the general industry concept. PostHogBase.ProductNames
716:4 warning 'Error tracking' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
718:207 warning Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept. PostHogBase.ProductNames
720:4 warning 'Upgrading from V1 to V2' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
722:4 warning Use 'X' instead of 'x'. Vale.Terms
722:4 error 'x' is repeated! Vale.Repetition
722:58 warning Use 'TypeScript' instead of 'Typescript'. Vale.Terms

@github-actions

github-actions Bot commented Aug 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

8.16 MiB (+8.9 KiB / +0.1%)

Largest changed named chunks
Chunk Gzip Δ vs master
df4cd0dd6698cb2c871cacbf96204758d75f61d1.js 20.4 KiB new
component---src-templates-template-tsx.js 5.7 KiB -19.4 KiB / -77.2%
app.js 2294.9 KiB +16.4 KiB / +0.7%
component---src-pages-self-driving-index-tsx.js 9.5 KiB -6.3 KiB / -39.8%
5d8a9c673a6b6b8e582448d50e82b40a2b3654c1.js 4.6 KiB new
component---src-pages-the-context-gap-report-index-tsx.js 3.1 KiB new
component---src-pages-pocket-guides-index-tsx.js 2.6 KiB -1.5 KiB / -36.2%
component---src-pages-compare-tsx.js 1.3 KiB new
component---src-pages-docs-references-version-unavailable-tsx.js 1.2 KiB new
4e5c9a1d4810c5f5c6325835bcfd7f436eb1af7e.js 10.2 KiB +1.2 KiB / +13.0%
component---src-pages-docs-ai-observability-learn-chapter-tsx.js 1.2 KiB new
component---src-pages-docs-session-replay-learn-chapter-tsx.js 1.1 KiB new
component---src-pages-docs-ai-observability-learn-tsx.js 1.1 KiB new
component---src-pages-docs-session-replay-learn-tsx.js 1.1 KiB new

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

Entrypoint Eager size Budget Modules
✅ app 18.42 MiB (+1541.4 KiB / +8.9%) report-only 2054
Largest modules in the app closure
Module Size
./src/data/mcp-tools.json 1081.4 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 758.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 370.0 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 + 126 modules 301.8 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.0 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).

@turnipdabeets
docs(node): document flush() as a span drain
b98df67
@turnipdabeets
docs(node): list tracing in the library comparison
08f7df0 
Adds a tracing key to the node page's features block and a Tracing column to the SDK comparison table.
@turnipdabeets
docs(tracing): add the posthog-node route to the install guides
ac32cc8 
The Node.js and Next.js guides now cover posthog-node alongside OpenTelemetry, and the pages that claimed no PostHog packages are needed say where that no longer holds.
@github-actions github-actions Bot removed the content PR only touches files under contents/ label Aug 31, 2026
@turnipdabeets
docs(tracing): retitle the install section now that Node has a non-OT…
9b39286 
…el route
@turnipdabeets
docs(tracing): say spans are server-only and fix the route-choice gui…
0fb4076 
…dance
@turnipdabeets
docs(tracing): drop the @posthog/next route, point at the Node guide
dbe06d3 
The SDK PR scopes tracing to posthog-node, so the Next.js page keeps its OpenTelemetry steps and only notes that server-side code can use the Node span API.
@turnipdabeets turnipdabeets mentioned this pull request Sep 2, 2026
Merged
23 tasks
turnipdabeets and others added 3 commits September 2, 2026 10:21
@turnipdabeets @claude
docs(node): document beforeSpanSend and span limits
2def3aa 
Adds the scrubbing hook and per-span cap sections, and the config rows
for the limits and the live-span bounds.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0138vKReknFeXLbvMyUX7fPZ
@turnipdabeets @claude
docs(node): note the exception reserve beyond the event cap
a65b490 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0138vKReknFeXLbvMyUX7fPZ
@turnipdabeets @claude
docs(node): correct the exception reserve and warn about stack contents
6b12635 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0138vKReknFeXLbvMyUX7fPZ
@christiaan-ph christiaan-ph mentioned this pull request Sep 4, 2026
Merged
5 tasks
@turnipdabeets @claude
docs(node): catch tracing up to the merged SDK behavior
fd7f813 
The event cap turned out to be absolute, and `maxAttributesPerEvent`,
`tracestate()`, the start options and sampled-flag propagation were
missing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013sbvfpzMFXrtwcz5S5zhtt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to product documentation, "Docs"

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@turnipdabeets