docs(sdk): Make the client event pipeline the authoritative step ordering - #18922
Merged
Conversation
The Client spec ran sampling as step 2 of the event pipeline, before scope application and before_send, and omitted the session update entirely. That contradicted the sessions spec, whose filter order places the session update after before_send and sampling last, so events dropped to save quota still count toward release health. Reorder the pipeline to match, add the ignored exception types and session update steps, and make the rationale normative: developer-controlled filters must not update the session, while quota-saving drops must not prevent it. Bump the Client spec to 3.0.0, since reordering mandated steps breaks existing implementations. Also remove the apply_to_scope timing note that contradicted the filter order within the sessions spec itself. Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
The step ordering was stated in full in both the Client and Sessions specs, which would let the two drift apart. Keep the ordering in the Client spec only and have the Sessions spec defer to it, retaining just the session-specific semantics of which drop reasons update the session. Also scope the reorder to SDKs that actually implement sessions. Sampling late only matters because a sampled-out event must still count toward release health, so SDKs without session support may keep sampling immediately after the disabled check and skip running processors and before_send on events they will discard. Point spec_depends_on from Sessions to Client rather than the reverse, since the session update hooks into the pipeline and the pipeline's reference back to sessions is conditional. Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
"immediately after the disabled check" already pins the position, and the following sentence covers what gets skipped. Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Refer to the pipeline steps by name instead of by number, so the prose does not break if a step is inserted and readers do not have to map numbers back to names. Collapse the three separate explanations of why sampling runs late into one, and state the non-session variant of the pipeline in a single sentence rather than splitting it across the session update step and a subsection. Retitle the ignoreErrors link so it names the option, since the anchor it points at is titled "Event Sampling". Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Split the sentence into one idea each and drop the dangling "therefore", which leaned on the previous paragraph to carry its reasoning. State the reason inline instead, and phrase the client report as a requirement rather than an aside. Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
Aligns the SDK specs so there’s a single authoritative definition of the client event pipeline ordering (including where session updates and error sampling occur), resolving the previous disagreement between the Client and Sessions specs.
Changes:
- Updates the Client spec’s event pipeline ordering to place session updates after
before_sendand move error sampling later, and records this as a breaking spec change. - Updates the Sessions spec to stop restating filter ordering and instead defer to the Client spec’s pipeline as the canonical reference.
- Updates the Hooks spec to reflect that
before_sendruns before the session update step in the pipeline.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| develop-docs/sdk/telemetry/sessions/index.mdx | Removes the duplicated/contradictory filter ordering and points readers to the Client spec’s authoritative event pipeline. |
| develop-docs/sdk/foundations/client/index.mdx | Makes the event pipeline ordering authoritative and updates ordering to include ignored exception types + session update before sampling. |
| develop-docs/sdk/foundations/client/hooks/index.mdx | Clarifies before_send placement relative to the session update in the pipeline. |
The hooks spec now describes before_send relative to the session update step, which only exists in the client pipeline as of 3.0.0, but its spec_depends_on still allowed 2.x. An SDK on 2.x has no session update step, making the guidance impossible to follow. Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Lms24
reviewed
Aug 3, 2026
Lms24
left a comment
Lms24
left a comment
Member
There was a problem hiding this comment.
thanks for updating. This looks good to me and reflects what we discussed in the last weeks. Just had some minor remarks regarding ordering.
coolguyzone
approved these changes
Aug 3, 2026
Giving ignored exception types their own step ahead of event processors mandated an order not every SDK follows — in JS, ignoreErrors is itself a client-level event processor. Merge it into the scope application step and spell out the three operations that happen there, noting that ignoreErrors MAY be implemented as an event processor. Make it explicit that scope data is merged before event processors run, since that ordering does affect behaviour and was only implied before. Also shorten the 3.0.0 changelog summary and reword the session update step. The summary keeps an em dash rather than a colon, because an unquoted YAML scalar cannot contain ": ". Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
7 tasks
cleptric
self-requested a review
August 11, 2026 13:51
cleptric
approved these changes
Aug 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DESCRIBE YOUR PR
The Client and Sessions specs disagreed on the event pipeline order: the Client spec sampled at step 2 and had no session update step, while the Sessions spec put the session update after
before_sendwith sampling last. We ratified the Sessions ordering, so this aligns the Client spec to it and makes that the only place the order is stated — Sessions now defers to it instead of restating it.As discussed internally:
Sampling runs late only so that sampled-out events still count toward release health, so SDKs without session support MAY keep sampling immediately after the disabled check.
Client spec bumped to
3.0.0as a breaking reorder — happy to drop it to2.3.0if you read this as correcting a spec that never matched real SDK behavior.IS YOUR CHANGE URGENT?
PRE-MERGE CHECKLIST