Using Timeline Context – ModelRiver Docs

Overview

The timeline is the most powerful feature of Request Logs. While other fields tell you what happened, the timeline tells you why and how. Every provider attempt, webhook delivery, and backend callback is displayed in chronological order, giving you complete lifecycle context.

Reading the timeline

Timeline components

Each timeline shows items in chronological order:

┌──────────────────────────────────────────────────────────┐
│  Request Timeline                                        │
│                                                          │
│  ⚠ Failover attempt    OpenAI gpt-4o       120ms        │
│  ✓ Main request        Anthropic claude     1,200ms     │
│  ✓ Webhook delivery    yourapp.com/hook     45ms        │
│  ✓ Backend callback    callback received    210ms       │
└──────────────────────────────────────────────────────────┘

Component types:

Icon	Type	Meaning
⚠ Amber	Failover attempt	Provider failed, moved to next
✓ Green	Main request	The successful (or final) provider attempt
✓ Green	Webhook delivery	Notification sent to your backend
✓ Green	Backend callback	Your backend's response received
✗ Red	Any component	Failed — requires attention

What the order tells you

The chronological order reveals causality:

Example 1: Clean success
  ✓ Main request → ✓ Webhook → ✓ Callback
  "Everything worked perfectly"
 
Example 2: Provider instability
  ⚠ Failover → ⚠ Failover → ✓ Main request
  "Primary and secondary providers failed, third succeeded"
 
Example 3: Webhook issue
  ✓ Main request → ✗ Webhook delivery
  "AI generation succeeded but notification failed"
 
Example 4: Complete failure
  ⚠ Failover → ⚠ Failover → ✗ Final attempt
  "All providers failed, no response available"

Timeline analysis patterns

Pattern 1: Read left to right for causality

Q: Why was this request slow (4,800ms)?
A: Timeline shows 3 failover attempts before success:
   ⚠ 800ms + ⚠ 1,200ms + ⚠ 1,600ms + ✓ 1,200ms = 4,800ms
   Root cause: Primary provider rate limited

Pattern 2: Check webhook status after successful AI

Q: User says they never received the result.
A: Timeline shows AI succeeded but webhook failed:
   ✓ Main request (success) → ✗ Webhook (timeout)
   Root cause: Webhook endpoint was down

Pattern 3: Trace callback completion

Q: Event-driven workflow isn't completing.
A: Timeline shows everything except callback:
   ✓ Main request → ✓ Webhook → ? Callback (progress...)
   Root cause: Backend isn't calling the callback URL

Pattern 4: Compare similar requests

Request A (fast, 1,200ms):
   ✓ Main request
   (No failovers needed)
 
Request B (slow, 4,500ms):
   ⚠ Failover → ⚠ Failover → ✓ Main request
   (Two failovers added 3,300ms)

Best practices for timeline analysis

Always check the full timeline

Don't jump to the response body first. The timeline provides context that changes how you interpret the response:

A successful response after 3 failovers suggests provider instability
A fast response from a fallback provider suggests the primary is down
Multiple webhook retries suggest endpoint issues

Click each timeline item

Each item has detailed information when expanded:

Failover attempts — Show the exact error that caused the failover
Main request — Shows full request/response bodies and token usage
Webhook deliveries — Show delivery status, error messages, and retry availability
Backend callbacks — Show callback payload and response data

Use timeline for incident response

During an incident:

Find the first failing request in the time window
Open its timeline to identify which component failed first
Check subsequent requests — do they all fail the same way?
The pattern tells you whether it's a provider outage, webhook endpoint issue, or configuration problem

Linking failed models to primary request

Failed model attempts are linked to the successful request via primary_req_id. The timeline automatically shows this chain, but you can also:

Click a failed attempt
Note its primary_req_id
Find the successful request with that ID
See the complete failover story

Event-driven timeline

For event-driven workflows, the timeline shows the complete three-step flow:

Step 1: AI generates response
  ✓ Main request (AI generation)
 
Step 2: Your backend processes the response
  ✓ Webhook delivery (with callback_url)
  ✓ Backend callback (your processing result)
 
Step 3: Final response delivered
  ✓ WebSocket broadcast to client

This end-to-end visibility is essential for debugging event-driven architectures.

Next steps

Timeline Documentation — Deep dive into each timeline component
Debugging Production Issues — Apply timeline analysis
Back to Best Practices — Return to the overview

Use timeline context for the full picture