docs: add troubleshooting section for common SRM causes and SDK mistakes (FT-1878)#277
docs: add troubleshooting section for common SRM causes and SDK mistakes (FT-1878)#277calthejuggler wants to merge 5 commits into
Conversation
Implements FT-1878. Adds a Troubleshooting category (position 11) under SDK-Documentation with three pages: - srm-and-exposure-issues.mdx: conditional exposure, audience filtering before treatment(), and not awaiting publish() before navigation - goal-undercounting.mdx: goal tracked before exposure, and metric time/property filter misconfiguration - sdk-context-best-practices.mdx: restructured as troubleshooting entries (symptom -> cause -> fix) covering multiple-context assignment conflicts and identity leakage after login/logout Review fixes applied: corrected JS SDK method name from getTreatment() to treatment() throughout (the existing docs and shared snippets use treatment() for JS; getTreatment is the Java/Go/.NET name), rewrote the conditional exposure wrong examples to actually demonstrate the one-path-skips-treatment pattern rather than showing a track-placement bug, fixed identical Python/Java publish examples to show the async variant as the wrong pattern, fixed a wrong experiment name in the Java goal example, and applied consistent style to match the existing SDK docs conventions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 1 minute Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughThis pull request adds a new Troubleshooting section under SDK Documentation, with a Docusaurus category configuration and three MDX pages: goal undercounting, SDK context best practices, and SRM and exposure issues. The pages cover exposure ordering, metric configuration, context lifecycle handling, user re-identification, conditional exposure, audience filtering, and publish timing. Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
✅ Deploy Preview for absmartly-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/APIs-and-SDKs/SDK-Documentation/troubleshooting/sdk-context-best-practices.mdx`:
- Around line 23-33: The JavaScript example in the SDK best practices page uses
the wrong API name, so update the example in handleRequest to use treatment()
instead of getTreatment() to match the JS SDK. Keep the surrounding
sdk.createContext and variant handling the same, and ensure the snippet
consistently reflects the actual JavaScript SDK method names.
- Around line 35-44: The example in the context best-practices doc should not
render before the exposure is published; update the request flow in the
handleRequest example so sdk.createContext(), treatment(), await
context.publish(), and context.finalize() happen before res.render() or any
response send. Keep the existing symbols handleRequest, context.publish, and
context.finalize, but reorder the steps so publishing completes first, then the
response is rendered.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 16ca061e-4e8c-4cae-8ed6-6c366c8616bc
📒 Files selected for processing (4)
docs/APIs-and-SDKs/SDK-Documentation/troubleshooting/_category_.jsondocs/APIs-and-SDKs/SDK-Documentation/troubleshooting/goal-undercounting.mdxdocs/APIs-and-SDKs/SDK-Documentation/troubleshooting/sdk-context-best-practices.mdxdocs/APIs-and-SDKs/SDK-Documentation/troubleshooting/srm-and-exposure-issues.mdx
Address CodeRabbit review on PR #277: the Wrong example used getTreatment() instead of the JS SDK's treatment(), and the Right example rendered the response before awaiting publish(), which is the exact mistake the SRM page warns against. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replace language tabs with a single TypeScript example per issue. The troubleshooting pages are about SDK integration mistakes rather than language-specific APIs, and a single example keeps the pages easier to scan while avoiding partial coverage across SDKs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ostics Point the diagnostic steps at the actual console pages: Events > Explore for inspecting the raw event stream, and the metrics overview for how time windows and property filters are configured. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Variant assignment is deterministic from the unit ID and experiment name, so multiple contexts for the same user do not cause them to land in different variants. The actual symptom is duplicate exposure events that over-count the user and skew the variant split (SRM). Reworded the symptom, cause, and code comment to reflect this. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Closing this draft. The content isn't at the standard we need yet — the troubleshooting entries need a rethink before they're worth merging. Ticket FT-1878 is moving back to To prioritise. |
1 participant
Summary
Implements FT-1878. Adds a Troubleshooting category (position 11) under SDK-Documentation with three pages covering the common SRM causes and SDK integration mistakes listed in the ticket.
Pages
srm-and-exposure-issues.mdx(sidebar position 1) — SRM causes:treatment()at different points per variant, or skipping it on one path)treatment()publish()before redirects/navigationgoal-undercounting.mdx(sidebar position 2) — goal undercounting causes:sdk-context-best-practices.mdx(sidebar position 3) — restructured as troubleshooting entries (symptom → cause → fix) per review:managing-the-context-lifecyclefor the full lifecycle reference rather than restating itReview fixes applied
This PR was reviewed via a multi-agent workflow. The following issues were found and fixed before opening:
JS SDK method name (major) — All JS tabs used
context.getTreatment(), but the JS SDK method iscontext.treatment().getTreatmentis the Java/Go/.NET name. The existing shared snippets (_shared/selecting-a-treatment/js/...) and existing SDK docs confirm this. Fixed throughout all three files.Conditional exposure wrong example didn't demonstrate conditional exposure (major) — The original "Wrong" code called
treatment()once before theif/else, identical to the "Right" code. The only difference was atrack()call inside one branch — a goal-undercounting bug, not an SRM bug. Rewrote the wrong examples to showtreatment()called only inside one code path (theif user.featureEnabledbranch), with the other path skipping the call entirely.sdk-context-best-practices.mdxstructure (major) — The page was structured as a best-practices explanation, not as troubleshooting entries. Rewrote it as two symptom → cause → fix entries so it fits the Troubleshooting category.Identical Python/Java publish examples (minor) — The Python and Java "Wrong" and "Right"
publish()blocks were identical becausepublish()is synchronous in those SDKs. Rewrote to showpublish_async()/publishAsync()as the wrong (fire-and-forget) pattern and awaiting it as the right pattern, with a note that synchronouspublish()is already safe.Wrong experiment name in Java goal example (minor) — The Java "Wrong" block for "Goal tracked before exposure" called
getTreatment("checkout_complete")(the goal name) instead ofgetTreatment("checkout_flow")(the experiment name). Fixed.Tab label casing (nit) — Changed
label="JavaScript"tolabel="Javascript"to match the existing SDK docs convention (the shared snippets and existing pages use lowercase-sJavascript).Build
Docusaurus build passes locally (
docusaurus build --no-minify). No broken links.Related tickets
🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation