Logging, Monitoring & Sentry
Relevant source files
The following files were used as context for generating this wiki page:
The system implements a multi-layered approach to logging and monitoring across the frontend, backend server, and database interactions. It provides real-time visibility into automation workflows, profile activities, and system health through WebSockets, structured logging, and integration with Sentry for error tracking.
The logging infrastructure supports two primary modes: Live Streaming, which consumes real-time events from the automation runner via WebSockets, and Archival Exploration, which allows developers to inspect historical log files stored on the server.
System Architecture & Data Flow
The monitoring architecture connects the automation engine with the user interface using a combination of HTTP APIs and WebSocket streams.
Log Data Pipeline
Real-time logs are generated during automation tasks and broadcasted through a WebSocket server. The frontend consumes these messages, parses them into structured LogEntry objects, and maintains a local buffer for display.
Error Tracking with Sentry
Sentry is integrated as the primary error-reporting tool. It is initialized early in the server lifecycle and acts as a middleware to capture unhandled exceptions before they reach the global error handler. On the frontend, breadcrumbs are manually added for critical events like WebSocket state changes.
Sources: server/index.ts:7-12, server/index.ts:101-103, frontend/src/hooks/useWebSocket.ts:208-212
Log Structures and Types
The system uses a standardized LogEntry interface to ensure consistency between real-time streams and static files.
Data Model: LogEntry
| Field | Type | Description |
|---|---|---|
message | string | The primary log content or payload. |
level | string | Severity level (info, warn, error, success, debug). |
ts | number | Unix timestamp of the event. |
source | string | The module or component that generated the log. |
profileName | string | (Optional) The automation profile associated with the event. |
workflowId | string | (Optional) ID of the active workflow. |
errorCode | string | (Optional) Specific error identifier for failures. |
diagnostics | string | (Optional) Verbose technical details for debugging. |
Sources: frontend/src/hooks/useWebSocket.ts:58-72, frontend/src/components/shared/useLogsState.ts:24-34
Real-time Monitoring (WebSocket)
The useWebSocket hook is the core of the real-time monitoring system. It manages the connection lifecycle, including authentication via Clerk tokens and exponential backoff for reconnections.
Reconnection Logic
When a connection is lost, the system schedules a reconnect using a jittered exponential backoff strategy to prevent hammering the server.
Frontend Log Management
The frontend provides a comprehensive LogsViewer component that allows users to filter, search, and manage log buffers.
Buffer Management
To prevent memory exhaustion during long-running automation sessions, the frontend implements a circular buffer:
- Mobile Buffer: 250 entries.
- Desktop Buffer: 1000 entries.
- Older entries are automatically evicted when new logs arrive via WebSocket.
Sources: frontend/src/components/shared/useLogsState.ts:60-61, frontend/src/components/shared/useLogsState.ts:218-226
Filtering & Visualization
Logs are visually categorized by severity using the LevelAppearance configuration:
- Error: Red background, semi-bold text, and a distinct left border.
- Warning: Yellow background for elevated visibility.
- Debug: Subtle styling for low-priority diagnostic information.
Sources: frontend/src/components/shared/useLogsState.ts:36-50, frontend/src/components/shared/LogsEntryList.tsx:181-193
Server-Side Monitoring
The backend server tracks every incoming HTTP request and monitors its own internal health.
Request Logging Middleware
Every HTTP request is assigned a unique ID and logged upon completion, including the method, URL, status code, and processing duration.
// server/index.ts:74-90
app.use((req, res, next) => {
const reqId = ++requestCounter
const start = Date.now()
;(req as any).id = reqId
res.on('finish', () => {
logger.info({
reqId,
method: req.method,
url: req.originalUrl,
status: res.statusCode,
duration: Date.now() - start,
}, 'HTTP request')
})
next()
})
Automation State Monitoring
The server detects "interrupted" runs during startup. If a previous session crashed, it identifies the orphaned PID and clears the stale state to prevent deadlocks in the automation runner.
Sources: server/index.ts:139-165
Database Reliability (Convex)
Monitoring extends to database connectivity. The convexClient implements a retry mechanism for transient network errors.
Retryable Error Conditions
The client specifically targets the following conditions for retries:
- HTTP 429: Rate limiting from the Convex cloud.
- HTTP 5xx: Server-side errors.
- Network Codes: Specific Node.js/libuv codes like
ECONNRESET,ETIMEDOUT, andEADDRNOTAVAIL.
Sources: server/shared/convexClient.ts:98-128
Conclusion
The logging and monitoring system is designed for both developer debugging and user-facing status updates. By combining Sentry for crash reporting, WebSockets for real-time progress, and structured logging for historical audits, the platform ensures that automation workflows remain observable and reliable.