docs: Add user docs for opening log files, level filtering, and formatting structured logs.

docs/src/user-guide/format-string-formatters.md

@@ -0,0 +1,33 @@
+# Formatters
+
+Formatters allow you to transform how field values are displayed. See below for a list of
+formatters.
+
+## Timestamp Formatter
+
+Converts Unix timestamps to human-readable date-time strings.
+
+**Usage:**
+`{field:timestamp[:options]}`
+
+**Options:**
+- Accepts a format string specifically for the date.
+- Uses [Day.js format tokens](https://day.js.org/docs/en/display/format).
+- Date string must escape colons with a backslash, e.g., `HH\:mm\:ss`.
+- If no format is specified, the default format is ISO 8601.
+
+**Examples:**
+- `{ts:timestamp}` → `2024-11-27T10:30:00Z`
+- `{ts:timestamp:YYYY-MM-DD}` → `2024-11-27`
+
+---
+
+## Round Formatter
+
+Rounds a numeric value to the nearest integer.
+
+**Usage:**
+`{field:round}`
+
+**Example:**
+- `{value:round}` → `5.7` becomes `6`

docs/src/user-guide/format-string-overview.md

@@ -0,0 +1,35 @@
+# Overview
+
+The log viewer can accept a format string to transform JSON logs into human-readable text.
+You can select which fields to display and how they should be formatted. The format string
+input can be found in the settings dialog.
+
+For example, for a JSON log with many fields:
+
+```json
+{
+    "ts": 1732733160216,
+    "level": "ERROR",
+    "message": "Failed to process payment transaction",
+    "trace_id": "abc123def456",
+    "span_id": "span_789xyz",
+    "service": "payment-service",
+    "environment": "production",
+}
+```
+
+You might want to show only:
+- timestamp
+- log level
+- message
+
+You can achieve this with the following format string `{ts:timestamp} {level} {message}`.
+`{ts:timestamp}` formats the timestamp field (Unix epoch) into a ISO 8601 date format.
+`{level}` and `{message}` display the field as is.
+
+The log is displayed as:
+```
+2024-11-27T18:46:00Z ERROR Failed to process payment transaction.
+```
+
+For detailed information about the format string syntax, see [Format String Syntax](format-string-syntax).

docs/src/user-guide/format-string-syntax.md

@@ -0,0 +1,64 @@
+# Format String Syntax
+
+- The format string is composed of arbitrary (“static”) text and field placeholders enclosed in
+  braces (`{` and `}`).
+    - Each brace or backslash in the static text must be escaped by a backslash.
+- Each field placeholder has the following form, consisting of three components (contained in
+  braces):
+
+    ```
+    {<field-name>[:<formatter-name>[:<formatter-options>]]}
+    ```
+
+    - `field-name` (required) defines the key of the field whose value should replace the
+      placeholder.
+        - Nested fields can be specified using periods (`.`) to denote hierarchy. E.g., the field
+          `{"a:" {"b": 0}}` may be denoted by `a.b`.
+        - Field names can contain any character except that each period, dollar sign, brace (left
+          or right), colon, or backslash must be escaped with a backslash.
+    - `formatter-name` (optional, unless `formatter-options` is specified) is the name of the
+      formatter to apply to the value before inserting it into the string.
+        - Formatter names can contain any character except a space (’ ‘) while each brace (left or
+          right), colon, or backslash must be escaped with a backslash.
+    - `formatter-options` (optional) defines any options for the formatter denoted by
+      `formatter-name`.
+        - Formatter options can contain any character except each brace (left or right), colon, or
+          backslash must be escaped with a backslash.
+- Finally, every format string contains an implicit trailing newline so that each formatted log
+  event ends with a newline.
+
+For example, consider the following log event:
+
+```
+{
+    "@timestamp": 1427153388942,
+    "level": "INFO",
+    "thread": 0,
+    "latency_secs": 56.4,
+    "an.odd.key{name}": "org.apache.hadoop.metrics2.impl.MetricsConfig: loaded properties from
+    hadoop-metrics2.properties"
+}
+```
+
+We can format this using the following YScope format string:
+
+```
+{@timestamp:timestamp:YYYY-MM-DD HH\:MM\:ss.SSS} {level} \{{thread}\} latency={latency_secs:round}
+{an\.odd\.key\{name\}}
+```
+
+- In the first placeholder, we have the field name `ts`, a formatter called `timestamp`, and the
+  formatter’s options which are a date format string.
+- The second and third placeholders simply stringify the values of the given fields.
+- The fourth placeholder uses the `round` formatter to round the field’s value; this placeholder
+  doesn’t specify any formatter options, so the defaults will be used.
+- The fifth placeholder is for a field whose name contains characters that require escaping.
+
+The formatted string will be:
+
+```
+2015-03-23 19:29:48.942 INFO {0} latency=56 org.apache.hadoop.metrics2.impl.MetricsConfig: loaded
+properties from hadoop-metrics2.properties
+```
+
+For a list of currently supported formatters, see [Formatters](format-string-formatters).

docs/src/user-guide/index.md

@@ -3,4 +3,51 @@
 This guide documents how to use and operate the YScope Log Viewer. Use the left sidebar (if it's
 hidden, click the {fas}`bars` icon) to navigate to specific docs.
 
-More details will be added soon.
+::::{grid} 1 1 2 2
+:gutter: 2
+
+:::{grid-item-card}
+:link: quick-start-overview
+Quick start
+^^^
+A guide to open files in the log viewer.
+:::
+
+:::{grid-item-card}
+:link: format-string-overview
+Format String
+^^^
+Docs for format strings.
+:::
+
+:::{grid-item-card}
+:link: log-level-filter
+Log Level Filter
+^^^
+Docs for filtering by log level.
+:::
+::::
+
+:::{toctree}
+:hidden:
+:caption: Quick start
+
+quick-start-overview
+:::
+
+:::{toctree}
+:hidden:
+:caption: Format String
+:glob:
+
+format-string-overview
+format-string-syntax
+format-string-formatters
+:::
+
+:::{toctree}
+:hidden:
+:caption: Log Level Filter
+
+log-level-filter
+:::

docs/src/user-guide/log-level-filter.md

@@ -0,0 +1,15 @@
+# Overview
+
+The log viewer offers two ways to filter log levels.
+
+## Severity Filtering
+Filter logs at or above a selected level. Click the level name (e.g., INFO) to show all logs at
+ or above that severity. For example, selecting INFO shows INFO, WARN, ERROR, and FATAL logs.
+
+![Severity filtering](../attachments/severity-filter.png)
+
+## Individual Filtering
+Select specific log levels to show or hide. Use the checkboxes next to each level name to toggle
+ visibility.
+
+![Individual level filtering](../attachments/individual-filter.png)

docs/src/user-guide/quick-start-overview.md

@@ -0,0 +1,11 @@
+# Overview
+
+This guide shows you how to open local and remote log files.
+
+## Local Files
+To open a local file, use the folder icon (📁) in the top-left corner. This will open a file
+browser where you can navigate to and select your log file.
+
+## Remote Files
+To open a remote file, append `/?filePath=<FILE_URL>` to the current URL. Just replace
+ `<FILE_URL>` with the URL of your log file.