Event Flow
What is Event Flow?
The Event Flow page shows you a live timeline of events as they move through your system. Think of it like a "live feed" showing what's happening right now - similar to watching server logs scroll by, but visual and easier to understand.
What You'll See
Timeline View:
●───[listing.created]───────────────●───[user.updated]───────────────●
│ │ │
Emitted → Processing → Completed Emitted → Failed Emitted → Processing
2:30:15 2:30:16 2:30:17 2:30:18 2:30:19 (Error) 2:30:20 2:30:21
Color coding:
🟢 Green = Completed successfully
🔴 Red = Failed
🟡 Yellow = Currently processing
🔵 Blue = Just emitted (waiting)
Why Use This Page?
Real-time debugging: "I just submitted a listing - did the email notification fire?"
Pattern spotting: "Are we getting a burst of user signups right now?"
Issue detection: "Why are all listing.created events failing suddenly?"
Performance monitoring: "How long is it taking to process events?"
Understanding the Timeline
Event Lifecycle States
Events move through 4 states:
┌─────────┐ ┌───────────┐ ┌───────────┐ ┌──────────┐
│ EMITTED │───▶│ PROCESSING│───▶│ COMPLETED │ │ FAILED │
│ (Blue) │ │ (Yellow) │ │ (Green) │ │ (Red) │
└─────────┘ └───────────┘ └───────────┘ └──────────┘
│ │ │
│ │ │
Event Handler Success!
created executing
Emitted (Blue): Event just created, waiting for processing Processing (Yellow): Handler is currently working on it Completed (Green): Successfully finished Failed (Red): Error occurred, moved to Dead Letter Queue
How to Read the Timeline
Event Card Layout
┌─────────────────────────────────────────────────────────────┐
│ 🔵 listing.created [Latest] │
│ │
│ Emitted: Mar 25, 2:30:15 PM │
│ Processing: Mar 25, 2:30:16 PM (1.2s) │
│ Completed: Mar 25, 2:30:17 PM (0.8s) │
│ │
│ Trace ID: trace-abc-123-def-456 │
│ Listener: EmailNotificationListener │
│ │
│ [▼ Click to expand for payload details] │
└─────────────────────────────────────────────────────────────┘
Timeline Indicators
The colored dot on the left shows the current state:
- 🔵 Blue dot = Just emitted
- 🟡 Yellow dot = Processing now
- 🟢 Green dot = Completed
- 🔴 Red dot = Failed
The vertical line connects events in chronological order (newest at top).
Using the Filters
Event Type Filter
Show only specific events:
listing.created- See only new listingsemail.sent- Monitor email deliveryuser.updated- Track profile changes
Use case: "I want to see if my test listing triggered the right events"
Status Filter
Show only events in specific states:
- All Statuses - Everything (default)
- Emitted - Events waiting to process
- Processing - Currently active
- Completed - Successfully done
- Failed - Errors (usually better to check Dead Letter Queue)
Use case: "Show me only failed events to see what's broken"
Trace ID Search
Find a specific event:
- Paste trace ID from logs or error messages
- Format:
trace-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Use case: "User reported issue with trace ID trace-abc-123 - find what happened"
Auto-Refresh Controls
Refresh Intervals
Choose how often to update the timeline:
| Interval | Best For | Note |
|---|---|---|
| 5s | Active debugging | Updates frequently, watch live |
| 10s | General monitoring | Good balance |
| 30s | Background watching | Less distracting |
| 60s | Occasional checks | Minimal updates |
| Off | Static analysis | Manual refresh only |
Pause/Resume
Pause (⏸️) stops auto-updates:
- Use when analyzing a specific event
- Prevents timeline from jumping as new events arrive
- Manual refresh button still works
Resume (▶️) starts auto-updates again
Connection Status
Connected (🟢): Auto-refresh working, receiving updates Paused (🟡): Updates paused, data is static Disconnected (🔴): Error connecting to server
Stats Summary Cards
Four quick metrics at a glance:
Total Events
Number of event types currently visible in the timeline
Completed (Green)
Events that finished successfully
- High number: System working well
- Low number: Check for failures
Processing (Yellow)
Events currently being handled
- High number: System busy
- Stuck for long time: Potential performance issue
Failed (Red)
Events that errored
- Any failures: Investigate immediately
- Click to jump to Dead Letter Queue
Common Use Cases
Scenario 1: Testing a New Feature
You just deployed a new feature and want to verify events fire correctly:
- Open Event Flow page
- Set refresh to 5s
- Filter by your event type (e.g.,
feature.used) - Trigger the feature
- Watch for the event to appear
- Verify it completes (green) not fails (red)
Success criteria: Event appears → Processes → Completes
Scenario 2: Debugging User Issues
User says "I updated my profile but didn't get a confirmation email":
- Ask user for approximate time of update
- Open Event Flow
- Filter by
user.updatedevents - Look for events around that time
- Check if
email.sentevent fired after - If email event is red → Check Dead Letter Queue for error details
What to look for:
- Did
user.updatedcomplete? (Should be green) - Did
email.sentfire? (Should appear in timeline) - Did
email.sentfail? (Red = check DLQ)
Scenario 3: Monitoring High Traffic
Marketing campaign just launched - is the system handling it?
- Open Event Flow
- Set refresh to 5s
- Watch the "Total Events" counter
- Monitor for:
- Sudden spikes in volume
- Events turning yellow (processing backlog)
- Events turning red (failures)
Warning signs:
- Processing count stays high = backlog building
- Failures increasing = system overloaded
- Events stuck in "Processing" > 10s = performance issue
Scenario 4: After System Recovery
Database was down, now it's back. Are events flowing again?
- Wait for database to be fully up
- Open Event Flow
- Trigger a test action (create a test listing)
- Watch for the event to flow: Blue → Yellow → Green
- If successful, bulk retry events from Dead Letter Queue
Success criteria: New events flow through all states successfully
Understanding Timing
Duration Calculations
The timeline shows how long each step took:
Emitted: 2:30:15 PM
Processing: 2:30:16 PM (1.2s) ← Time from emit to start processing
Completed: 2:30:18 PM (2.0s) ← Time spent processing
Total time: 3.2 seconds from creation to completion
What's Normal?
| Phase | Normal | Warning | Critical |
|---|---|---|---|
| Emit → Processing | < 1s | 1-5s | > 5s |
| Processing Time | < 100ms | 100-500ms | > 500ms |
| Total Duration | < 2s | 2-10s | > 10s |
Long durations indicate:
- High system load
- Slow database queries
- External API delays
- Inefficient event handlers
Expanding Event Details
Click any event card to see:
Full Timeline
- Exact timestamps for each phase
- Duration calculations
- Timezone information
Listener Information
- Which handler processed it
- Processing duration
- Success/failure status
Error Details (for failed events)
- Full error message
- Stack trace
- Error classification
Metadata
- User ID who triggered it
- Deployment ID
- Correlation ID for tracing
Payload (when available)
- Event data in JSON format
- What information the event carried
- Useful for debugging data issues
Best Practices
✅ Do
- Use 5s refresh when actively debugging
- Filter by event type to reduce noise
- Pause when analyzing specific events
- Check timestamps to understand timing
- Expand failed events to see error details
- Use trace ID search to find specific events
- Monitor during deployments to catch issues early
❌ Don't
- Don't leave 5s refresh on all day - wastes resources
- Don't ignore yellow events - check if they're stuck
- Don't assume green = perfect - check duration too
- Don't use this for historical analysis - only shows recent events
- Don't panic over single failures - look for patterns
Limitations & Future Improvements
Current Limitations
In-Memory Only: Events are stored in memory, not database
- Events disappear after server restart
- Limited history (last 50-100 events)
- No persistence for audit trail
Aggregated View: Shows event types, not individual instances
- See "listing.created: 5 events" not 5 separate entries
- Can't track individual event payloads in detail
- Phase 3 will add full event persistence
What's Coming in Phase 3
- Database persistence: Full event history
- Individual event tracking: See every single event
- Search by payload: Find events by data content
- Historical analysis: View events from weeks ago
- Advanced filtering: Filter by user, data values, etc.
Troubleshooting
Q: I don't see any events
A: Check:
- Is auto-refresh enabled? (Not paused)
- Are filters too restrictive? (Clear filters)
- Is the system actually processing events? (Check Event System Dashboard)
- Try manual refresh button
Q: Events are stuck in "Processing"
A: Yellow events staying yellow = handlers are slow or stuck
- Check system load
- Look for long-running database queries
- May need to restart stuck handlers
Q: All events are failing
A: Red events everywhere = critical system issue
- Check database connectivity
- Check external services (email, APIs)
- Review recent code deployments
- Escalate to engineering immediately
Q: The timeline jumps around
A: New events arriving push old ones down
- Pause auto-refresh to stabilize view
- Or increase refresh interval to 30s/60s
Q: Can I export this data?
A: Not from this page - use Event Metrics for exportable data
Keyboard Shortcuts
| Key | Action |
|---|---|
Space | Pause/Resume auto-refresh |
R | Manual refresh |
F | Focus filter input |
Esc | Clear filters |
Related Pages
- Event System Dashboard - Overview metrics
- Dead Letter Queue - Manage failed events
- Event Metrics - Historical analytics and export
- System Health - Overall system status
Quick Reference Card
EVENT FLOW QUICK GUIDE
🎯 Purpose: Watch events happen in real-time
🔵 Blue = Emitted (waiting)
🟡 Yellow = Processing (working)
🟢 Green = Completed (success)
🔴 Red = Failed (error)
⏱️ Refresh: 5s (debugging) | 30s (monitoring) | Off (analysis)
🔍 Filters: Event type | Status | Trace ID
⚡ Actions: Pause | Refresh | Expand details
🚨 Alerts: Any red events = check Dead Letter Queue
Remember: Event Flow is your "live TV" for watching the system work. Use it for real-time debugging and monitoring active issues!