custom events by mantrakp04 · Pull Request #1290 · stack-auth/stack-auth

mantrakp04 · 2026-03-25T22:44:53Z

Enhance documentation tools integration
Enhance error handling and API response for documentation tools
Refactor askStackAuth key to ask_stack_auth in API documentation
Enhance analytics and spans functionality in backend

- Added new SQL migrations for Clickhouse to support spans and events, including new columns and views. - Implemented validation for analytics events and spans, ensuring proper structure and data integrity. - Introduced new API endpoints for uploading analytics spans and events, improving data collection capabilities. - Updated existing analytics event handling to accommodate new fields and ensure compatibility with the updated database schema. - Added tests for analytics event insertion and validation to ensure reliability and correctness. These changes improve the analytics framework, enabling better tracking and analysis of user interactions.

vercel · 2026-03-25T22:44:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stack-auth-hosted-components	Ready	Preview, Comment	Mar 27, 2026 0:44am
stack-backend	Ready	Preview, Comment	Mar 27, 2026 0:44am
stack-dashboard	Ready	Preview, Comment	Mar 27, 2026 0:44am
stack-demo	Ready	Preview, Comment	Mar 27, 2026 0:44am
stack-docs	Ready	Preview, Comment	Mar 27, 2026 0:44am

coderabbitai · 2026-03-25T22:45:12Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c682f659-765b-4e01-9f53-4c237d583aa9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch custom-events

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

greptile-apps · 2026-03-25T22:49:35Z

Greptile Summary

This PR ships the custom events / tracing feature for Stack Auth's analytics SDK. It adds client-side and server-side trackEvent(), captureException(), startSpan(), super-properties, a new /analytics/spans/batch backend route, a new analytics_internal.spans ClickHouse table, and shared validation/sanitization helpers. All critical issues from the previous review round have been addressed.

Issues found:

In events.tsx, system events logged through logEvent receive trace_id: generateUuid() — a random UUID — rather than null, creating orphaned traces inconsistent with SDK convention.
SPANS_VIEW_SQL is executed twice in runClickhouseMigrations() — first call is redundant.
The events batch route contains a duplicate user-auth guard.

Confidence Score: 4/5

Safe to merge; no data-loss or security regressions found. All prior critical concerns are addressed.

The implementation is thorough, well-tested, and resolves all issues flagged in the previous review. The one logic issue (random trace_id on system events) affects analytics data quality but is not a runtime error or security vulnerability. Remaining findings are minor style/redundancy issues.

apps/backend/src/lib/events.tsx (trace_id generation for system events), apps/backend/scripts/clickhouse-migrations.ts (redundant SPANS_VIEW_SQL call)

Important Files Changed

Filename	Overview
apps/backend/src/lib/events.tsx	Refactored logEvent to insert analytics rows via insertAnalyticsEvents; adds span-based telemetry export, but generates random trace_id for every system event instead of null.
apps/backend/src/app/api/latest/analytics/events/batch/route.tsx	Events batch route expanded to support server-sent custom events, session replay ID validation against DB, and proper from_server attribution.
apps/backend/src/app/api/latest/analytics/spans/batch/route.tsx	New spans batch endpoint with proper auth checks; client auth guard for user_id/team_id override is correctly implemented.
apps/backend/scripts/clickhouse-migrations.ts	Adds spans table, trace_id and from_server columns; SPANS_VIEW_SQL is executed twice (harmless but redundant).
apps/backend/src/lib/analytics-validation.ts	New shared validation helpers for event/span types and lone-surrogate sanitization; centralizes logic previously duplicated across routes.
apps/backend/src/lib/spans.tsx	New insertSpans helper with lone-surrogate sanitization, analogous to insertAnalyticsEvents.
packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts	Adds trackEvent, captureException, register/unregister super-properties, startSpan, and span batcher; fixes origin check with URL parsing; fetch patch is now applied once globally.
packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts	Adds server-side trackEvent, captureException, startSpan, middleware(); user context resolved once per span rather than at end time, avoiding N concurrent API calls.
packages/template/src/lib/stack-app/apps/implementations/server-event-batcher.ts	New server-side batcher that groups items by session key; correctly uses Symbol.for to share state across CJS/ESM dual-package builds.
packages/template/src/lib/stack-app/apps/implementations/tracing.ts	New SpanImpl using Map for attribute storage (avoids prototype pollution); correctly implements async context propagation.
packages/template/src/lib/stack-app/apps/implementations/event-tracker.ts	Extended event tracker with rage click, scroll depth, clipboard, error, and custom event support; configurable thresholds via env vars.
packages/template/src/lib/stack-app/apps/implementations/analytics-events.ts	Shared client-side validation helpers for event names, timestamps, payloads, and replay link options.
packages/stack-shared/src/interface/crud/analytics.ts	Adds AnalyticsBatchEvent, AnalyticsBatchSpan types and AUTO_CAPTURED_ANALYTICS_EVENT_TYPES; well-structured with clear client/server permission split.

Sequence Diagram

sequenceDiagram
    participant Browser as Browser SDK
    participant Server as Server SDK
    participant EventsAPI as /analytics/events/batch
    participant SpansAPI as /analytics/spans/batch
    participant CH as ClickHouse

    Note over Browser: trackEvent() / captureException()
    Browser->>Browser: EventTracker._enqueueEvent()
    Browser->>Browser: ClientSpanBatcher.push()
    Browser-->>EventsAPI: POST (client auth, keepalive)
    Browser-->>SpansAPI: POST (client auth, keepalive)

    Note over Server: trackEvent() / startSpan()
    Server->>Server: ServerBatcher.push(event, session)
    Server->>Server: ServerBatcher.push(span, session)
    Server-->>EventsAPI: POST (server auth, grouped by session)
    Server-->>SpansAPI: POST (server auth, grouped by session)

    EventsAPI->>EventsAPI: Validate auth type + event_type
    EventsAPI->>EventsAPI: Resolve session_replay_id from DB
    EventsAPI->>CH: insertAnalyticsEvents()

    SpansAPI->>SpansAPI: Validate auth type + span_type
    SpansAPI->>CH: insertSpans()

    Note over CH: ReplacingMergeTree deduplicates spans by span_id

_{Reviews (5): Last reviewed commit: "Enhance client analytics event validatio..." | Re-trigger Greptile}

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts

apps/backend/src/app/api/latest/analytics/spans/batch/route.tsx

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts

- Added validation to prevent client analytics spans from overriding user_id or team_id. - Refactored _superProperties in client and server app implementations to use Map for better performance and memory management. - Updated methods to handle super properties using Object.fromEntries for compatibility with the new Map structure. These changes improve data integrity and optimize property management in the analytics framework.

mantrakp04 · 2026-03-25T23:04:34Z

@greptile-ai review

packages/template/src/lib/stack-app/apps/implementations/tracing.ts

- Removed unused browserSessionId from analytics event batch upload and query functions to streamline data handling. - Updated SQL queries in tests to include new event types and ensure proper validation messages. - Enhanced test cases to reflect changes in permissions for accessing spans, improving overall test coverage. These changes optimize the analytics event processing and strengthen the integrity of test validations.

- Removed unused browserSessionId from client-side and server-side event tracking to streamline the analytics process. - Updated the `trackEvent` method to ensure immediate flushing of events, enhancing reliability in event delivery. - Improved documentation for `trackEvent` usage, clarifying the behavior of fire-and-forget calls and the importance of flushing analytics. These changes optimize event handling and enhance the clarity of the analytics framework documentation.

mantrakp04 · 2026-03-25T23:56:48Z

@greptile-ai review additionally give extra attention to hard to read slop, non DRY code, n etc

apps/backend/src/lib/spans.tsx

packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts

- Added a new utility function `stripLoneSurrogates` to handle lone surrogate characters in strings, ensuring compatibility with ClickHouse's JSON parser. - Refactored `sanitizeAnalyticsEventData` and `insertSpans` functions to utilize the new `stripLoneSurrogates` function for data sanitization before processing. - Improved code organization by moving the lone surrogate handling logic from `events.tsx` to a dedicated validation module. These changes enhance data integrity and prevent potential parsing errors in analytics event handling.

- Updated the type of `_waitUntil` to use `Promise<unknown>` for improved type safety. - Refactored the `_trackAutoCapturedEvent` method to simplify the handling of request options. - Enhanced the `_normalizeRequestArg` method to ensure proper type handling for headers and options. - Improved global state management in `server-event-batcher` by using a more explicit type definition. - Adjusted header reading functions in `tracing.ts` to enhance type safety and clarity. These changes improve code maintainability and ensure better type safety across the server app implementation.

- Introduced a `Set` for known event types in the `PageClient` component to enhance performance and readability. - Updated the filtering logic for custom event types to utilize the new `Set`, ensuring more efficient checks. - Adjusted type definitions in `server-app-impl` and `server-event-batcher` to use `Promise<unknown>` for better type safety. These changes streamline event type management and enhance type safety across the application.

mantrakp04 · 2026-03-26T01:28:11Z

@greptile-ai review and check for best practices and clean code with a high focus on readability

packages/stack-shared/src/interface/crud/analytics.ts

- Removed browser_session_id from SQL queries and test assertions to streamline analytics data handling. - Updated related functions to ensure consistency in event type queries and improve clarity in test cases. These changes enhance the focus on relevant event data and improve the overall structure of analytics queries.

…ences - Removed all instances of browser_session_id from analytics queries and documentation to streamline event tracking and improve clarity. - Updated related SQL queries and documentation to reflect the changes in session replay linkage, focusing on sessionReplayId and sessionReplaySegmentId. - Improved type safety in server app specifications by adjusting the waitUntil promise type. These changes optimize the analytics framework and enhance the overall clarity of event handling.

- Introduced a new validation function, `isValidClientAnalyticsEventType`, to ensure client analytics events do not use server-only event types. - Updated the analytics validation logic to differentiate between client and server event types, improving clarity and security in event handling. - Adjusted documentation to reflect the new validation rules for client-sent analytics events. These changes strengthen the integrity of analytics event processing and enhance the overall structure of event type management.

mantrakp04 · 2026-03-26T02:36:40Z

@greptile-ai review

- Introduced a new endpoint for ingesting OpenTelemetry traces in OTLP/HTTP JSON format, allowing backend services to send trace data as analytics spans. - Implemented validation and sanitization for incoming trace data, ensuring only valid spans are processed. - Enhanced error handling for invalid payloads and added support for server or admin authentication. - Updated analytics validation to accept additional formats for OpenTelemetry IDs, improving flexibility in trace identification. These changes expand the analytics capabilities and improve the integration with OpenTelemetry for better observability.

Copilot AI review requested due to automatic review settings March 25, 2026 22:44

github-actions bot assigned mantrakp04 Mar 25, 2026

vercel bot had a problem deploying to Preview – stack-auth-hosted-components March 25, 2026 22:45 Failure

Copilot started reviewing on behalf of mantrakp04 March 25, 2026 22:45 View session

mantrakp04 review requested due to automatic review settings March 25, 2026 22:46

Merge branch 'dev' into custom-events

745ff93

vercel bot had a problem deploying to Preview – stack-auth-hosted-components March 25, 2026 22:47 Failure

mantrakp04 changed the base branch from dev to dario-likes-mcps March 25, 2026 22:47

Merge branch 'dario-likes-mcps' into custom-events

5e5cdb8

vercel bot had a problem deploying to Preview – stack-auth-hosted-components March 25, 2026 22:47 Failure

update pnpm lock

3b420e1

greptile-apps bot reviewed Mar 25, 2026

View reviewed changes

vercel bot deployed to Preview – stack-auth-hosted-components March 25, 2026 22:50 View deployment

vercel bot deployed to Preview – stack-auth-hosted-components March 25, 2026 23:01 View deployment

greptile-apps bot reviewed Mar 25, 2026

View reviewed changes

packages/template/src/lib/stack-app/apps/implementations/tracing.ts Outdated Show resolved Hide resolved

vercel bot deployed to Preview – stack-auth-hosted-components March 25, 2026 23:34 View deployment

vercel bot deployed to Preview – stack-auth-hosted-components March 25, 2026 23:51 View deployment

greptile-apps bot reviewed Mar 26, 2026

View reviewed changes

apps/backend/src/lib/spans.tsx Show resolved Hide resolved

packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts Show resolved Hide resolved

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts Show resolved Hide resolved

mantrakp04 added 3 commits March 25, 2026 17:52

vercel bot deployed to Preview – stack-auth-hosted-components March 26, 2026 01:22 View deployment

greptile-apps bot reviewed Mar 26, 2026

View reviewed changes

packages/stack-shared/src/interface/crud/analytics.ts Show resolved Hide resolved

vercel bot deployed to Preview – stack-auth-hosted-components March 26, 2026 02:08 View deployment

vercel bot deployed to Preview – stack-auth-hosted-components March 26, 2026 02:14 View deployment

vercel bot deployed to Preview – stack-auth-hosted-components March 26, 2026 02:37 View deployment

vercel bot deployed to Preview – stack-auth-hosted-components March 27, 2026 00:39 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

custom events#1290

custom events#1290
mantrakp04 wants to merge 14 commits intodario-likes-mcpsfrom
custom-events

mantrakp04 commented Mar 25, 2026

Uh oh!

vercel bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Mar 25, 2026 •

edited

Loading

Review skipped

Uh oh!

greptile-apps bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mantrakp04 commented Mar 25, 2026

Uh oh!

Uh oh!

mantrakp04 commented Mar 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mantrakp04 commented Mar 26, 2026

Uh oh!

Uh oh!

mantrakp04 commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

mantrakp04 commented Mar 25, 2026

Uh oh!

vercel bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

greptile-apps bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mantrakp04 commented Mar 25, 2026

Uh oh!

Uh oh!

mantrakp04 commented Mar 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mantrakp04 commented Mar 26, 2026

Uh oh!

Uh oh!

mantrakp04 commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel bot commented Mar 25, 2026 •

edited

Loading

coderabbitai bot commented Mar 25, 2026 •

edited

Loading

greptile-apps bot commented Mar 25, 2026 •

edited

Loading