docs(aio): document posthog_ custom metadata for vercel and traceloop

[Radu-Raicea]

Problem

The Vercel AI SDK and Traceloop AI observability paths now promote posthog_-prefixed metadata to top-level custom properties (see #73578), but the onboarding docs didn't mention it. Users setting up either integration had no way to know they can attach their own filterable dimensions (environment, tags, etc.) to $ai_generation events.

Changes

• Vercel AI SDK: added a posthog_environment example to the experimental_telemetry.metadata snippet and a note explaining that any posthog_-prefixed metadata field is captured as a custom property with the prefix stripped, while other metadata isn't captured.
• Traceloop: added an optional step showing that posthog_-prefixed association properties are forwarded as custom properties.

How did you test this code?

Docs-only change (onboarding .tsx). No automated tests added. The edits reuse existing onboarding components (CodeBlock, Markdown, Blockquote) already imported in each file.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

Docs update

This PR is the docs update for the behavior restored in #73578.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Requested from a Slack thread as the docs follow-up to #73578, which stopped dropping posthog_ custom properties on the Vercel and Traceloop OTel ingestion paths. I inspected that PR's diff to confirm the exact behavior (prefix stripped, only set if unset, $-prefixed and distinct_id excluded) and mirrored it in the two matching onboarding docs. Traceloop's doc is the hosted-integration flow, so the custom-property step documents setting association properties in the user's own code rather than on the integrations page.

---

Created with PostHog from a Slack thread

[github-actions]

Hey @Radu-Raicea! 👋

It looks like your git author email on this PR isn't your @posthog.com address (radu@raicea.com). Since you're on the PostHog team, it's worth pointing your local git author email at your @posthog.com address. Why it matters:

• Consistent work identity in git history — internal tooling that attributes commits to team members keys off your @posthog.com address.
• Keeps team contributions easy to tell apart from external community ones when scanning history.

You can fix it for this repo with:

git config user.email "you@posthog.com"

Or set it globally with git config --global user.email "you@posthog.com". No need to redo this PR — just a nudge for next time. 🙂

[github-actions]

🤖 CI report

ℹ️ Docs preview — preview build triggered

Docs from this PR will be published at posthog.com.

Project	Preview	Updated (UTC)
posthog.com	Open preview	Jul 24, 2026, 5:16 PM

The preview should be ready in about 10 minutes. Open the preview at /handbook/engineering/.

[greptile-apps]

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/onboarding/product-analytics/traceloop.tsx:67-69
**Traceloop properties are discarded**

When a user follows this example, Traceloop exports the association property into the `traceloop.association.properties.*` namespace, which the ingestion middleware deletes without promoting the value, causing the documented `environment` property to be absent from the PostHog event.

_{Reviews (1): Last reviewed commit: "docs(aio): document posthog_ custom meta..." | Re-trigger Greptile}

[stamphog]

Docs-only change adding accurate onboarding copy for the posthog_-prefixed custom metadata feature. I checked the Greptile concern against the actual traceloop ingestion middleware (traceloop.ts) and its existing test suite: promotePosthogCustomMetadata runs before the traceloop.association.properties.* keys are stripped, and a passing test already confirms posthog_-prefixed association properties are promoted (e.g. posthog_env → env) exactly as the new docs describe — the bot's claim that the value is discarded is incorrect.

• greptile-apps[bot] reviewed the current head.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	0L, 0F substantive, 33L/2F incl. docs/generated/snapshots — within ceiling
tier	✓	T0 auto-approve: T0-deterministic (33L, 2F, single-area, docs)
stamphog 2.0.0b3		.stamphog/policy.yml @ fc211d0 · reviewed head ea08511

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-07-24 17:55 UTC	Run
prod-us	✅ Deployed	2026-07-24 18:16 UTC	Run
prod-eu	✅ Deployed	2026-07-24 18:18 UTC	Run