Run Logs
Real-time visibility into action execution with structured logging
Run Logs
Action runs emit structured log entries that provide real-time visibility into execution progress. These logs are stored in the database and can be streamed via Server-Sent Events (SSE).
Overview
Every action run produces log entries at key lifecycle moments:
| Phase | Events Emitted |
|---|---|
| Start | extraction_started with resource list |
| Per Resource | resource_started, resource_completed or resource_failed |
| Per Slice | slice_started, slice_completed (for large resources) |
| Lifecycle | lease_acquired, heartbeat, run_interrupted |
| Completion | run_completed or run_failed |
Accessing Logs
Fetch All Logs
vai actions logs run_abc123curl https://api.virtuousai.com/api/v1/action-runs/run_abc123/logs \
-H "Authorization: Bearer $VAI_API_KEY"Stream Logs (SSE)
For real-time updates during execution:
curl -N https://api.virtuousai.com/api/v1/action-runs/run_abc123/logs/stream \
-H "Authorization: Bearer $VAI_API_KEY" \
-H "Accept: text/event-stream"Events arrive as newline-delimited JSON:
data: {"event": "resource_started", "data": {"resource": "profiles", "completed_count": 0, "total_count": 3}}
data: {"event": "resource_completed", "data": {"resource": "profiles", "rows": 12500, "files": 3}}Log Entry Structure
Each log entry contains:
{
"id": "log_xyz789",
"level": "info",
"event": "resource_completed",
"message": "Completed profiles: 12,500 rows, 3 files",
"data": {
"resource": "profiles",
"rows": 12500,
"files": 3,
"duration_seconds": 45.2
},
"worker_id": "worker-abc-123",
"attempt": 1,
"occurred_at": "2026-01-23T10:30:45Z"
}| Field | Description |
|---|---|
level | info, warning, or error |
event | Machine-readable event type |
message | Human-readable description |
data | Structured payload (varies by event) |
worker_id | Worker that emitted the log |
attempt | Retry attempt number (1 = first try) |
Event Reference
Extraction Events
| Event | Level | When Emitted |
|---|---|---|
extraction_started | info | Extraction begins |
resource_started | info | Starting a resource |
resource_completed | info | Resource finished successfully |
resource_failed | error | Resource encountered error |
slice_started | info | Starting a time-window slice |
slice_completed | info | Slice finished |
extraction_completed | info | All resources done |
Lifecycle Events
| Event | Level | When Emitted |
|---|---|---|
lease_acquired | info | Worker took ownership |
heartbeat | info | Periodic health signal (every 5 min) |
run_interrupted | warning | SIGTERM received, saving checkpoint |
run_cancelled | warning | User cancelled the run |
run_completed | info | Successful completion |
run_failed | error | Terminal failure |
Recovery Events
| Event | Level | When Emitted |
|---|---|---|
watchdog_recovery | warning | Watchdog recovered stale run |
watchdog_fast_recovery | warning | Fast recovery after deployment |
watchdog_cancelled | warning | Watchdog cancelled abandoned run |
Example: Tracking a Large Extraction
For a Klaviyo extraction with sliced events:
10:30:00 [info] extraction_started - Starting extraction from klaviyo
10:30:01 [info] resource_started - Extracting profiles (1/3)
10:30:45 [info] resource_completed - Completed profiles: 12,500 rows
10:30:46 [info] resource_started - Extracting events (2/3), sliced
10:30:47 [info] slice_started - Slice 1/104 for events
10:31:30 [info] slice_completed - Slice 1/104: 8,500 rows
10:32:15 [info] slice_completed - Slice 2/104: 9,200 rows
... (102 more slices)
14:45:00 [info] resource_completed - Completed events: 892,000 rows
14:45:01 [info] resource_started - Extracting lists (3/3)
14:45:30 [info] resource_completed - Completed lists: 45 rows
14:45:31 [info] run_completed - Run completed successfully in 4h 15mFiltering Logs
Filter by level to focus on issues:
# Errors only
curl ".../logs?level=error"
# Warnings and errors
curl ".../logs?level=warning"Best Practices
- Stream for long runs — Use SSE for real-time visibility on extractions
- Check warnings —
run_interruptedevents indicate deployment recoveries - Review slice progress — For large resources, slice events show actual progress
- Correlate with retries — Use
attemptfield to track retry history
Log entries are retained for 30 days. For longer retention, export to your own logging system.