Solavel Solavel Docs

System event logs

docs/solavel/system-event-logs.md

Who can use this: Solavel staff with Admin or Super Admin URL / Route: /admin/system-event-logs/*, /admin/errors/*, /admin/beta-reports/*, /admin/user-monitor/* Plan / feature gate: Always on for staff

Purpose

System event logs are how Solavel staff track what happened across the platform — server errors, beta-tester bug reports, payment webhooks, outbound emails, and significant user actions. This page covers the four staff tools that read from those logs and the public ingest endpoints that feed them.

What gets logged

The system_events table receives entries from three places:

  1. In-process events — when a controller wants to leave a breadcrumb (login, plan change, organization create) it writes a system_events row directly.
  2. Captured exceptions — every uncaught exception is caught by the global error handler and written as a system_events row of kind error. Critical errors are also relayed to a Telegram channel by the system error notifier.
  3. External ingest — both Solabooks and Solavel Workspace (when it existed) post into POST /api/system-events/ingest with their own events. The Tap webhook at POST /api/webhooks/tap and the beta-report ingest at POST /api/beta-reports also write to the log.

Step by step

Browse the event log

  1. Open /admin/system-event-logs (admin.system-event-logs.index). You get a paginated, filterable table.
  2. Filter by kind (error / info / audit), date range, source app, or user.
  3. Click any row to see the full event detail at admin.system-event-logs.show.
  4. To pull a copy out, use Export CSV (admin.system-event-logs.export, /admin/system-event-logs/export/csv). The export respects whichever filter is active.

Triage server errors

  1. Open /admin/errors (admin.errors.index). This is the same data narrowed to errors only, with stack traces unfolded.
  2. Click an entry to view at /admin/errors/{id} (admin.errors.show).
  3. Errors that match a Telegram-notified pattern have a small badge — those have already been pushed to the engineering channel.

Review beta reports

  1. Open /admin/beta-reports (admin.beta-reports.index). Reports come in from the client-side beta report form and from the Solabooks app's relay endpoint.
  2. Click a report to read it (admin.beta-reports.show). You can change its status (open, in progress, fixed, won't fix) via PATCH admin.beta-reports.update.
  3. Each report links to the user who filed it, the URL they were on, and the system event row from system_events.ingest if there is one.

Watch live workspaces

  1. Open /admin/user-monitor (admin.user-monitor.index). It lists every active workspace with last-seen times.
  2. Click a workspace key to see detail (admin.user-monitor.show).
  3. Health check runs an on-demand probe (admin.user-monitor.health-check) — it pings the workspace's bootstrap endpoint and shows the response inline.

Inspect contact-form submissions

  1. Open /admin/contact-messages (admin.contact-messages.index).
  2. Click a message to view (admin.contact-messages.show).
  3. Reply directly via POST admin.contact-messages.reply — the reply is sent through the standard mailer and recorded in the event log.

Beta report flow

The user-side flow:

  1. A signed-in user opens the Reports link in the sidebar (client.beta-reports.index).
  2. They click Create (client.beta-reports.create) and submit (POST /client/beta-reports, client.beta-reports.store).
  3. The submission is also relayed to the central error pipeline by the beta-report observer — every beta report writes a system_events row, sends a Telegram notification, and shows up in /admin/beta-reports.
  4. They can re-open their own report later at client.beta-reports.show.

There is also a public ingest endpoint at POST /api/beta-reports. It is signature-checked by the VerifySolavelSyncSignature rule (HMAC) so only the Solabooks app — which holds the shared secret — can call it.

Public ingest endpoints

Three POST endpoints accept data from outside the central app:

URL Auth Purpose
POST /api/beta-reports HMAC signature Solabooks forwards beta reports.
POST /api/errors/ingest HMAC signature Solabooks forwards captured exceptions.
POST /api/system-events/ingest (none — open) Generic event sink. Risk: this endpoint has only the api middleware. It is reachable without auth or signature. Treat it as untrusted input until tightened.
POST /api/tenancy/organizations/projects/sync HMAC signature Solabooks keeps the org-project mapping in sync.
POST /error-report (none — open) Public error-report POST used by un-authed pages (the marketing site). Lightly throttled.

Telegram error notifier

When an unhandled exception is captured, a notifier posts a short summary to a Telegram channel. The exact destination is configured by TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables. The same channel receives high-priority notes from the beta-report observer. Staff are expected to monitor that channel for live incidents.

Confirmation: the bot token and channel id are set in the production environment file. To check who currently receives alerts, look at config/services.php and the matching environment values.

Permissions / restrictions

  • All /admin/system-event-logs/*, /admin/errors/*, /admin/beta-reports/*, /admin/user-monitor/*, and /admin/contact-messages/* pages require Admin (EnsureAdmin).
  • The user-side beta report endpoints (client.beta-reports.*) require sign-in plus the view-reports permission for visibility (Owners, Managers, and Members all hold it).

Common problems

  • "Event log empty for the last 24 hours." — Either the application is healthy or the writer is down. Check the queue worker; events go through the queue.
  • A beta report does not show in /admin/beta-reports. Check /admin/system-event-logs first — the relay may have written an event but the beta-reports table write may have failed.
  • Telegram alerts stopped arriving. The bot may be muted or the chat id changed. Verify the token and chat id, then trigger a known error to test.

Related

Source: docs/solavel/system-event-logs.md ← All documentation