diff --git a/images/resources/view-instance-logs-with-filters.png b/images/resources/view-instance-logs-with-filters.png new file mode 100644 index 00000000..2187e01f Binary files /dev/null and b/images/resources/view-instance-logs-with-filters.png differ diff --git a/images/resources/view-instance-logs.png b/images/resources/view-instance-logs.png index bf56b075..8aba2de5 100644 Binary files a/images/resources/view-instance-logs.png and b/images/resources/view-instance-logs.png differ diff --git a/maintenance-ops/monitoring-and-alerting.mdx b/maintenance-ops/monitoring-and-alerting.mdx index 30faee38..b2ac6629 100644 --- a/maintenance-ops/monitoring-and-alerting.mdx +++ b/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. + + + + +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: 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--.csv` where `` is the export time in UTC. + + + 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. + ### 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: +``` + +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: +``` For diagnosing sync latency, see [Diagnosing Sync Latency](/debugging/troubleshooting#diagnosing-sync-latency).