Document new dashboard logs functionality and capabilities

maintenance-ops/monitoring-and-alerting.mdx

@@ -100,24 +100,145 @@ Access instance logs through the [PowerSync Dashboard](https://dashboard.powersy
 
 You can manage logs with the following options:
 
-* **Filter Options**: Filter logs by level (`Note`, `Error`, `Warning`, `Debug`) and by date range.
+* **Log Type**: Switch between **API logs** (from the PowerSync Service) and **Replication logs**.
+* **Log Levels**: Show or hide `Info`, `Error`, `Warn`, and `Debug` entries.
+* **Time Range**: Limit results to a relative window (last 15 minutes, last hour, etc.) or a custom range. The available window depends on your plan's retention period.
+* **Sort Order**: Sort by newest or oldest first.
+* **Display Options**: Show metadata pills on each entry, show stack traces for errors, and tail logs in real time.
 
-* **Sorting**: Sort logs by newest or oldest first.
+### Search and Filter Logs
 
-* **Metadata**: Display metadata like `user_id` and `user_agent` in the logs if available.
+<Frame>
+  <img src="/images/resources/view-instance-logs-with-filters.png" />
+</Frame>
+
+The **Search** input above the log list accepts free-text terms and structured `alias:value` filters. Type a query and the results update as you type.
+
+#### Free-Text Search
+
+Type bare words to match anywhere in the raw log entry. Matching is case-insensitive, and every word must match (AND):
+
+```
+checkpoint stream
+```
+
+Wrap a phrase in double quotes to match the exact sequence:
+
+```
+"sync stream complete"
+```
+
+Free-text search matches against the full entry, including the message text and every metadata field. This is independent of the **Display Options** toggle that controls whether metadata pills are rendered, so a match on a metadata value still returns the entry even if the pills in the UI are hidden.
+
+#### Field Filters
+
+Use `alias:value` to filter on a specific structured field. Unlike free-text search, a field filter only matches the named field, not the rest of the log entry. Repeating the same alias matches any of the listed values (OR within a field, AND across fields):
+
+```
+user_id:<user-id-a> user_id:<user-id-b> error:PSYNC_S2001
+```
+
+Quote values that contain spaces:
+
+```
+close_reason:"client closing stream"
+```
+
+The following aliases are supported for API logs. For most fields the alias matches the canonical field name; `error` and `lag` keep a short form because their underlying paths are awkward to type. You can also type the short aliases shown in parentheses; they are normalised to the canonical name on submit.
+
+| Alias                | Field          | Description                                              |
+| -------------------- | -------------- | -------------------------------------------------------- |
+| `user_id` (`user`)   | `user_id`      | The authenticated user ID for the sync session.          |
+| `client_id` (`client`) | `client_id`  | The client device ID.                                    |
+| `rid` (`request`)    | `rid`          | The request ID. Matches a started or complete entry.     |
+| `error`              | `error_code`   | A specific PSYNC error code (see [Error Codes](/debugging/error-codes)). |
+| `close_reason` (`reason`) | `close_reason` | Why the sync session closed.                          |
+
+For Replication logs:
+
+| Alias | Field             | Description                                                                  |
+| ----- | ----------------- | ---------------------------------------------------------------------------- |
+| `lag` | `replication_lag` | Replication lag in seconds. Used with a numeric comparison (see below). |
+
+#### Numeric Comparisons
+
+The `lag` filter accepts `>`, `>=`, `<`, `<=`, and `=`:
+
+```
+lag:>=5
+```
+
+Only one numeric comparison is allowed per field. Combining `lag:>5 lag:<10` is rejected.
+
+#### Filtering on Other Fields
+
+The **Add filter** button in the toolbar lists the aliases for the active log type. Log entries can contain many additional fields, and you can filter on any of them using `alias:value` syntax directly in the search bar. For example:
+
+```
+buckets:1
+```
+
+Filters are evaluated against the matching field on each log entry.
+
+You can also add a metadata field as a filter directly from any log entry. Enable the **Metadata** display option to render each entry's structured fields as pills. Click a pill to open its menu and choose **Add filter**:
+
+* If the field matches one of the known aliases, the value is added as that filter.
+* If not, the value is added as an unknown-field filter.
+
+This is the quickest way to filter on fields you spot in the logs without remembering their names.
+
+#### Combined Example
+
+You can mix free-text terms, known aliases, and unknown fields in a single query:
+
+```
+checkpoint sync user_id:123 checkpoint:>=1224
+```
+
+This matches entries containing both `checkpoint` and `sync` in the message, with `user_id` equal to `123` and a `checkpoint` field greater than or equal to `1224`.
+
+### Export Logs
+
+Click the **Download** button on the right side of the toolbar to export the currently visible log entries to a CSV file. The export reflects the active log type, time range, log levels, and search query, so you can narrow the result set before downloading.
 
-* **View Mode**: Tail logs in real-time or view them statically.
+The CSV uses fixed columns for the most useful fields and collapses anything else into a trailing `metadata` JSON column:
 
-* **Stack Traces**: Option to show or hide stack traces for errors.
+| Column         | Description                                                                 |
+| -------------- | --------------------------------------------------------------------------- |
+| `timestamp`    | ISO 8601 timestamp of the entry.                                            |
+| `level`        | Log level (`info`, `error`, `warn`, `debug`).                                |
+| `message`      | Formatted log message.                                                       |
+| `user_id`      | Authenticated user ID (API logs).                                            |
+| `client_id`    | Client device ID (API logs).                                                 |
+| `rid`          | Request ID (API logs).                                                       |
+| `error_code`   | PSYNC error code if the entry has one.                                       |
+| `close_reason` | Close reason for sync session entries.                                       |
+| `metadata`     | JSON object containing every other top-level field on the entry.             |
+
+The file is named `powersync-logs-<instance-id>-<timestamp>.csv` where `<timestamp>` is the export time in UTC.
+
+<Note>
+  The export only includes entries currently loaded in the view. If you have not scrolled to load more entries with **Load More**, those entries are not included in the CSV.
+</Note>
 
 ### Correlating Sync Sessions
 
-To find a specific users session in the Service logs, filter on their `user_id`. Two events describe each sync session:
+To find a specific user's session in the API logs, search for their `user_id`:
+
+```
+user_id:<user-id>
+```
+
+Two events describe each sync session:
 
 * **Sync stream started**: logged when the client connects. Fields include `user_id`, `client_id`, `app_metadata` (if set), `client_params`, `user_agent`, and `rid` (request id).
 * **Sync stream complete**: logged when the session ends. Fields include `user_id`, `client_id`, `app_metadata` (if set), `operations_synced`, `operation_counts` (broken down by `put`, `remove`, `move`, `clear`), `data_synced_bytes`, `data_sent_bytes`, `stream_ms` (session duration), `close_reason`, and `rid`.
 
-Both events share the same `rid`, so a started/complete pair for a single session can be matched by filtering on it.
+Both events share the same `rid`, so you can match a started/complete pair for a single session by searching for it:
+
+```
+rid:<request-id>
+```
 
 For diagnosing sync latency, see [Diagnosing Sync Latency](/debugging/troubleshooting#diagnosing-sync-latency).