# Server Logs Viewer

## Overview

The **Server Logs** module is the central place for administrators to browse, search, and analyze system logs recorded by the application. It provides a real-time and historical view of everything happening behind the scenes — errors, warnings, user actions, API communications, and debug information.

Logs are stored in two places:

- **Current active content** — the live, actively written log database.
- **Archive** — older logs moved to long-term storage.

When you open the module, it automatically imports any logs that were temporarily written to disk (for example, if the database was unavailable) and adds them to the current view.

---

## Main Listing (Log Table)

When you open the module, you see a paginated table with the following columns:

| Column | Description |
|--------|-------------|
| **Session** | A short identifier grouping related log entries together. Clicking a session ID filters the entire list to show only entries from that session. |
| **Date** | The exact timestamp when the log was recorded. |
| **Level** | The severity of the log entry: **Critical**, **Error**, **Warning**, or **Info**. |
| **Message** | The main content of the log. Messages are color-coded and formatted to highlight error types, module names, file references, and API calls. |
| **Module** *(hidden by default)* | The source module or code path that generated the log. |

### Pagination

You can choose how many rows to display per page — from **5** up to **1,000** entries. The total count of matching records is shown above the table.

---

## Filters

Use the filter panel to narrow down what you see. The following filters are available:

| Filter | What it does |
|--------|--------------|
| **Text** | Searches inside the log message and log ID. Supports advanced syntax (see below). |
| **User** | Show only logs generated by a specific user. |
| **Level** | Show only logs of selected severity levels (Critical, Error, Warning, Info). |
| **Session** | Show only logs belonging to a specific session ID. |
| **Stacktrace** | Search inside the technical stacktrace attached to logs. |
| **Date** | Pick a date range to limit results to a specific period. |
| **Source** | Filter by the origin of the log (e.g., disk-based logs during database outages). |
| **Load from** | Switch between **current active content** and the **archive** database. |

### Advanced Text Search

The text filter supports special syntax for precise searches:

- `!content:database` — messages containing "database"
- `!content!:database` — messages **not** containing "database"
- `!content:^database` — messages starting with "database"
- `!content:database$` — messages ending with "database"
- `!content:database;content:insert` — messages containing both "database" **and** "insert"
- `!content:database;content!:insert` — messages containing "database" but **not** "insert"
- `!context:hasKey:exception` — messages whose attached context contains a key named "exception"
- `!context:empty:0` — messages that have a context attached
- `!context:empty:1` — messages that have no context attached

> **Note:** Context filtering searches the full, uncompressed context data. Because this happens after reading from the database, it may be slower and will scan all records without pagination limits.

---

## Row Options (Actions)

Select one or more rows in the table to unlock actions from the options menu:

| Action | What it does |
|--------|--------------|
| **Log details** | Opens a popup showing the full message, context data, user, and stacktrace for the selected log. Only works when **one** row is selected. |
| **Show more / less like this** | Adjusts the text filter to include or exclude the selected message text. |
| **Limit interval** | Narrows the date filter to a short window around the selected log (1 min, 2 min, 5 min, up to 2 hours). |
| **Report login stats** | Generates an HTML report analyzing login attempts, including usernames, IP addresses, and browser statistics. |
| **Report FluX logs** | Exports all FluX communication logs as a detailed, color-coded HTML report. |
| **Report FluX logs, filtered** | Same as above, but shows only log lines with severity level 3 and higher. |
| **Report core errors** | Exports all core PHP errors as an HTML report with full stacktraces and file references. |
| **Report core errors, unique** | Same as above, but removes duplicate entries so you see only one example of each unique error. |
| **Report top log counts** | Generates an HTML report that groups identical messages together and shows how many times each occurred. You can expand/collapse groups and sort by count or message text. |
| **Report top log sizes** | Generates an HTML report listing the largest log entries by total size (message + context + stacktrace), helping identify storage-heavy logs. |
| **Report SaElectronicInvoice logs** | Exports a detailed, formatted HTML report for SaElectronicInvoice API communications, showing requests and responses side by side. |

---

## Log Details Popup

Clicking **Log details** opens a detailed view of a single log entry:

- **Message** — the full log text, preserving line breaks and formatting.
- **Level** — the severity and source of the log.
- **Session** — clickable link that filters the main list by this session.
- **Date** — the exact timestamp.
- **Context** — additional structured data attached to the log. This can include API requests/responses, variables, or other debugging info. Each context item is shown with its name and value.
- **User** — the user who triggered the log, if known.
- **Stacktrace** — the technical call path (sequence of code files and methods) that led to the log being recorded. The stacktrace is color-coded by system area (engine, app, modules, plugins, etc.) to make it easier to read.

---

## How Logs Work on the Backend

### What gets logged?

The system records logs automatically from many sources:

- **PHP errors and warnings** (E_ERROR, E_WARNING, E_NOTICE, E_DEPRECATED, etc.)
- **Database errors**
- **User authentication events** (logins, failed attempts)
- **API communications** (FluX, SaElectronicInvoice, and other integrations)
- **Custom application events** triggered by modules and plugins
- **System performance data** (execution times, memory usage)

### Log structure

Each log entry contains:

- **ID** — a unique identifier
- **Source** — where the log came from (e.g., `MAIN`, `Disk`, or a specific module)
- **Log Level** — severity (Critical, Error, Warning, Info)
- **Message** — the human-readable description
- **Context** — optional extra data (serialized and compressed for efficiency)
- **Stacktrace** — optional technical backtrace
- **User ID** — who was logged in when the event occurred
- **Session ID** — groups related logs together
- **Timestamp** — when the event happened

### Resilience during outages

If the database becomes unavailable, the system does not lose logs. Instead, it writes them to disk temporarily. When you open the Logs module, it automatically detects these disk-stored logs and imports them back into the database. You will see a notification like:

> *Imported 42 messages from disk (from 2024-01-15 08:30:00 to 2024-01-15 09:15:00)*

Corrupted disk files are moved to a skipped folder so they do not block the import process.

### Archiving

Over time, logs are moved from the active database to an archive table to keep the main view fast. You can switch to the **archive** data source using the filter panel to investigate older events.

---

## Tips for Using the Log Viewer

1. **Start broad, then narrow down** — Use the date filter first, then add text filters to find specific issues.
2. **Use session grouping** — If you find an error at a specific time, click the session ID to see everything else that happened in the same request.
3. **Use timeline limits** — When you find one error, use the timeline limit options (1 min, 5 min, etc.) to see what happened immediately before and after.
4. **Check reports for patterns** — Instead of scrolling through thousands of identical errors, use **Report top log counts** to see which errors happen most frequently.
5. **Investigate large logs** — Use **Report top log sizes** if you suspect certain logs are consuming excessive storage space.
6. **Switch to archive** — If you cannot find an event in the current logs, remember to switch the **Load from** filter to **archive**.
