real-time-streams by mintlify[bot] · Pull Request #203 · mixpanel/docs

mintlify · 2026-08-28T19:21:09Z

Mintlify

10 threads from 2 users in Mintlify

docs/real-time-event-streams/overview.mdx
- Howard Chen: should the customer be aware of "Phase 1", "Phase 2"? view comment
- Howard Chen: Maybe just "Events Log" and "failed events log" is just one of possible status? view comment
- Howard Chen: will not have full payload for failed event log, only http response view comment
docs/real-time-event-streams/states-and-monitoring.mdx
- Howard Chen: we turn the status to error, including unhealthy (destination unreachable or rate limited), after 5 times retry. The ... view comment
- Howard Chen: I assume some metrics will not be supported in beta, as the callout section says view comment
- Howard Chen: we should mention that whenever a sync is paused due to errors, we will send the notification to the creator of the s... view comment
docs/real-time-event-streams/delivery-and-reliability.mdx
- Howard Chen: retries are processed in the same queue, not the different one view comment
- Howard Chen: the sync will be paused for 4xx auth error. see "[Event Sink Service] authentication failure (401 or 403)" in ERD view comment
- Howard Chen: this is incorrect- we do not queue events and resume. please see "Lifecycles" in ERD [https://app.notion.com/p/mxpnl/... view comment
docs/real-time-event-streams/setup.mdx
- Howard Chen: not support in beta. should we show this? view comment

- Created docs/real-time-event-streams/overview.mdx - Created docs/real-time-event-streams/setup.mdx - Created docs/real-time-event-streams/delivery-and-reliability.mdx - Created docs/real-time-event-streams/states-and-monitoring.mdx - Updated docs.json Mintlify-Source: dashboard-editor

- Updated docs/real-time-event-streams.mdx - Updated docs/real-time-event-streams/states-and-monitoring.mdx - Updated docs/real-time-event-streams/delivery-and-reliability.mdx - Updated docs/real-time-event-streams/overview.mdx - Updated docs/real-time-event-streams/setup.mdx - Updated docs.json Mintlify-Source: dashboard-editor

ryancurtis1 · 2026-08-28T19:22:42Z

@copilot resolve the merge conflicts in this pull request

greptile-apps · 2026-08-28T19:24:16Z

Confidence Score: 3/5

The PR is not ready to merge because the documentation root remains empty and the required troubleshooting and FAQ coverage is still missing.

Findings

Missing troubleshooting and FAQ ▶

_{Reviews (12) · Last reviewed commit: "Merge branch 'main' into real-time-strea..."}

greptile-apps · 2026-08-28T19:24:19Z

+
+{/* PLACEHOLDER: Describe which changes can be made in place (event types, filters, template, auth) and which require pausing the Sync. Clarify how in-flight events are handled during edits. */}
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Delivery and reliability" icon="shield-check" href="/docs/real-time-event-streams/delivery-and-reliability">
+    Retries, failed events log, and at-least-once delivery.
+  </Card>
+
+  <Card title="States and monitoring" icon="chart-line" href="/docs/real-time-event-streams/states-and-monitoring">
+    Destination and Sync states, plus how to monitor health.
+  </Card>
+</CardGroup>


Missing troubleshooting and FAQ

The new documentation ends without the troubleshooting and FAQ material required by the automatically discovered STREAM-310 acceptance criteria, leaving customers without consolidated recovery guidance for common configuration failures.

Source Used: Linear — Public docs

Resolve merge conflict in docs.json by taking the updated structure from main branch. The main branch restructured guides navigation, moving guides from guides-by-use-case/empower-your-team to a flatter structure with better grouping. Since the real-time-streams branch is adding documentation about real-time event streams and not modifying the guides structure, we accept the updated version from main. Co-authored-by: ryancurtis1 <176308989+ryancurtis1@users.noreply.github.com>

Copilot · 2026-08-28T19:25:33Z

@copilot resolve the merge conflicts in this pull request

✅ Merge conflicts resolved. I've merged the origin/main branch into real-time-streams and resolved the conflict in docs.json by accepting the updated guides navigation structure from main. The conflict was caused by guide path restructuring (e.g., guides-by-use-case/empower-your-team/mcp → guides/mcp), which is now reflected in the merged result.

The merge commit has been created and pushed.

mherrman · 2026-08-31T20:16:54Z

+- **Sync** — a rule that binds a set of filtered events and a Liquid payload template to a Destination.
+- **Failed events log** — a 72-hour record of events that could not be delivered after all retries, retained with the destination HTTP response for debugging.
+
+<Tip>


this is an empty callout in the docs. should add something here or remove

@copilot can you remove this empty callout please

Done. Removed the empty callout at line 59 of overview.mdx.

mherrman · 2026-08-31T20:17:46Z

@@ -0,0 +1,3 @@
+---
+title: "docs/real-time-event-streams"


to the greptile comments point the way this is displayed current should be updated. i don't think this page necessarily needs a bunch of content but we should have something (at least a title instead of the path)

@copilot can you fix this please

Done. Replaced the path-based title with "Real-Time Event Streams" and added a proper description to match the pattern of other index pages.

Remove the empty <Tip> block that contained only a placeholder comment at line 59 of docs/real-time-event-streams/overview.mdx. Co-authored-by: ryancurtis1 <176308989+ryancurtis1@users.noreply.github.com>

Replace the path-based title "docs/real-time-event-streams" with a proper customer-facing title and add a description to match the pattern of other index pages in the docs. Co-authored-by: ryancurtis1 <176308989+ryancurtis1@users.noreply.github.com>

howardchen11 · 2026-09-14T18:59:36Z

+
+Up to **5 retries per event** with exponential backoff over approximately **12 minutes**:
+
+| Attempt | Delay before attempt |


the code does up to 5 total attempts (1 initial + 4 retries) with exponential backoff starting at 200ms (~3s total); 429s honor Retry-After, capped at 10s.

retries run inline in the same consumer path, so we keep the window to seconds - a long in-process backoff would block the batch and hold PubSub messages. longer recovery is handled by pausing the stream and surfacing the error, not by retrying for minutes. Can we update the table to match?

howardchen11 · 2026-09-14T19:03:06Z

+
+- **Destination** — the webhook endpoint and its authentication configuration.
+- **Sync** — a rule that binds a set of filtered events and a Liquid payload template to a Destination.
+- **Failed events log** — a 72-hour record of events that could not be delivered after all retries, retained with the destination HTTP response for debugging.


In beta the failed log is an aggregated roll-up: one row per stream + status + response code per window, with the response status code, a short error detail, and counts. no per-event entries, no headers/body, no payload samples. Can we align the description?

howardchen11 · 2026-09-14T19:03:39Z

+| `5xx` response | Yes | Server-side error at the destination. |
+| Connection timeout / network error | Yes | Includes DNS failures and TLS handshake errors. |
+| `429 Too Many Requests` | Yes | Handled via backpressure. See [Rate limits](#rate-limits-and-backpressure). |
+| `4xx` response (other than 429) | No | Surfaced immediately as a destination configuration error. |


Only 401/403 are terminal (auth). Other 4xx (400/404/422…) are retried as "unreachable" and, if they keep failing, the stream is paused (DESTINATION_UNHEALTHY) - so they are retried and do pause, the opposite of this section. Can we correct it?

howardchen11 · 2026-09-14T19:04:11Z

+| `unhealthy` | Deliveries are partially failing but no event has exhausted its retries yet. Investigate soon. |
+| `paused_rate_limit` | Temporarily paused after a `429` response from the destination. Auto-resumes when the destination recovers. |


In beta there's no unhealthy running state and no paused_rate_limit auto-resume.

a terminal failure - including rate-limit after retries - pauses the stream and surfaces the health reason. Can we mark these as GA-target and drop them from the beta states table?

howardchen11 · 2026-09-14T19:05:11Z

+| 5 | 2 minutes |
+| 6 | 10 minutes |
+
+Retries are processed in a separate queue, so they never block new events from streaming.


Small correction: retries run in the same consumer path, not a separate queue.

howardchen11 · 2026-09-14T19:06:00Z

+
+## Delivery guarantees at a glance
+
+- **At-least-once delivery.** Every outbound request includes an `X-Mixpanel-Insert-Id` header so you can deduplicate on your side.


This is a current gap - the X-Mixpanel-Insert-Id header isn't sent yet. i've filed a ticket and will fix it. https://linear.app/mixpanel/issue/STREAM-860/send-x-mixpanel-insert-id-header-on-webhook-deliveries

can we drop the X-Mixpanel-Insert-Id statements for now and add them back once it lands?

- Updated docs/real-time-event-streams/delivery-and-reliability.mdx Mintlify-Source: dashboard-editor

- Updated docs/real-time-event-streams/overview.mdx Mintlify-Source: dashboard-editor

- Updated docs/real-time-event-streams/setup.mdx Mintlify-Source: dashboard-editor

- Updated docs/real-time-event-streams/setup.mdx - Updated docs/real-time-event-streams/delivery-and-reliability.mdx Mintlify-Source: dashboard-editor

- Updated docs/real-time-event-streams/delivery-and-reliability.mdx Mintlify-Source: dashboard-editor

- Updated docs/real-time-event-streams/states-and-monitoring.mdx Mintlify-Source: dashboard-editor

mintlify Bot added 2 commits August 19, 2026 16:50

mintlify Bot requested review from a team as code owners August 28, 2026 19:21

mintlify Bot requested review from junhouse and rssebastian-mp August 28, 2026 19:21

mintlify Bot deployed to staging August 28, 2026 19:22 View deployment

ryancurtis1 marked this pull request as draft August 28, 2026 19:22

Copilot started work on behalf of ryancurtis1 August 28, 2026 19:23 View session

greptile-apps Bot reviewed Aug 28, 2026

View reviewed changes

Copilot finished work on behalf of ryancurtis1 August 28, 2026 19:26

Copilot AI requested a review from ryancurtis1 August 28, 2026 19:26

mintlify Bot deployed to staging August 28, 2026 19:27 View deployment

ryancurtis1 requested review from howardchen11 and mherrman August 28, 2026 20:25

mherrman reviewed Aug 31, 2026

View reviewed changes

Copilot started work on behalf of ryancurtis1 September 1, 2026 19:09 View session

Remove empty callout placeholder from overview.mdx

620465d

Remove the empty <Tip> block that contained only a placeholder comment at line 59 of docs/real-time-event-streams/overview.mdx. Co-authored-by: ryancurtis1 <176308989+ryancurtis1@users.noreply.github.com>

Copilot finished work on behalf of ryancurtis1 September 1, 2026 19:10

Copilot started work on behalf of ryancurtis1 September 1, 2026 19:11 View session

Copilot finished work on behalf of ryancurtis1 September 1, 2026 19:12

mintlify Bot deployed to staging September 1, 2026 19:21 View deployment

mintlify Bot deployed to staging September 1, 2026 19:24 View deployment

howardchen11 reviewed Sep 14, 2026

View reviewed changes

mintlify Bot deployed to staging September 15, 2026 20:23 View deployment

mintlify Bot added 3 commits September 15, 2026 20:30

Updated mintlify pages

69e8da3

- Updated docs/real-time-event-streams/delivery-and-reliability.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

0b36899

- Updated docs/real-time-event-streams/delivery-and-reliability.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

3b3834d

- Updated docs/real-time-event-streams/delivery-and-reliability.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging September 15, 2026 20:33 View deployment

Updated mintlify pages

b16dd7c

- Updated docs/real-time-event-streams/overview.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging September 15, 2026 20:45 View deployment

mintlify Bot added 2 commits September 15, 2026 20:54

Updated mintlify pages

3ea1a58

- Updated docs/real-time-event-streams/overview.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

fcb2e1f

- Updated docs/real-time-event-streams/overview.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging September 15, 2026 20:57 View deployment

mintlify Bot added 4 commits September 15, 2026 20:57

Updated mintlify pages

bcd5505

- Updated docs/real-time-event-streams/overview.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

aeb409b

- Updated docs/real-time-event-streams/setup.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

289141b

- Updated docs/real-time-event-streams/setup.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

300b433

- Updated docs/real-time-event-streams/setup.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging September 15, 2026 21:02 View deployment

mintlify Bot added 5 commits September 15, 2026 21:02

Updated mintlify pages

9ba8762

- Updated docs/real-time-event-streams/setup.mdx - Updated docs/real-time-event-streams/delivery-and-reliability.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

7d95a12

- Updated docs/real-time-event-streams/delivery-and-reliability.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

dff18b1

- Updated docs/real-time-event-streams/states-and-monitoring.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

bd7d2a9

- Updated docs/real-time-event-streams/states-and-monitoring.mdx Mintlify-Source: dashboard-editor

Updated mintlify pages

4daf522

- Updated docs/real-time-event-streams/states-and-monitoring.mdx Mintlify-Source: dashboard-editor

mintlify Bot deployed to staging September 15, 2026 21:07 View deployment

Merge branch 'main' into real-time-streams

ebf723e

ryancurtis1 approved these changes Sep 15, 2026

View reviewed changes

mintlify Bot deployed to staging September 15, 2026 21:09 View deployment

ryancurtis1 marked this pull request as ready for review September 15, 2026 21:09

ryancurtis1 enabled auto-merge (squash) September 15, 2026 21:27

mherrman self-requested a review September 15, 2026 21:34

mherrman approved these changes Sep 15, 2026

View reviewed changes

ryancurtis1 merged commit 3f3f409 into main Sep 15, 2026
6 checks passed

ryancurtis1 deleted the real-time-streams branch September 15, 2026 21:35


		Up to 5 retries per event with exponential backoff over approximately 12 minutes:

		\| Attempt \| Delay before attempt \|

		\| `unhealthy` \| Deliveries are partially failing but no event has exhausted its retries yet. Investigate soon. \|
		\| `paused_rate_limit` \| Temporarily paused after a `429` response from the destination. Auto-resumes when the destination recovers. \|


		## Delivery guarantees at a glance

		- At-least-once delivery. Every outbound request includes an `X-Mixpanel-Insert-Id` header so you can deduplicate on your side.

Uh oh!

Conversation

mintlify Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Mintlify

Uh oh!

ryancurtis1 commented Aug 28, 2026

Uh oh!

greptile-apps Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 3/5

Findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Aug 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mintlify Bot commented Aug 28, 2026 •

edited

Loading

greptile-apps Bot commented Aug 28, 2026 •

edited

Loading