docs: Add user docs for opening log files, level filtering, and forma…

…tting structured logs. (#132)

Co-authored-by: Kirk Rodrigues <[email protected]>

docs/src/user-guide/.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

docs/src/user-guide/format-struct-logs-formatters.md

@@ -0,0 +1,38 @@
+# Formatters
+
+Formatters allow you to transform how field values are displayed. Below we describe all available
+formatters and their options.
+
+## Timestamp formatter
+
+Converts millisecond Unix timestamps to human-readable date-time strings.
+
+### Usage
+```
+{field:timestamp[:options]}
+```
+
+### Options
+A [Day.js format string](https://day.js.org/docs/en/display/format) for the date and time.
+
+**Default:** `YYYY-MM-DDTHH:mm:ssZ` (ISO 8601)
+
+### Examples
+Assuming the field `ts` is `1732703400000`:
+
+* `{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}
+```
+
+### Examples
+Assuming the field `value` is `5.7`:
+
+* `{value:round}` → `6`

docs/src/user-guide/format-struct-logs-overview.md

@@ -0,0 +1,37 @@
+# Overview
+
+The log viewer can format structured (e.g. JSON) logs as plain text using a format string. The
+format string allows you to select which fields to include and how they should be formatted. You can
+configure the format string through the settings ({fas}`gear`) dialog.
+
+For example, for a JSON log with many fields:
+
+```json
+{
+  "ts": 1732733160216,
+  "level": "ERROR",
+  "message": "Failed to process payment.",
+  "trace_id": "abc123def456",
+  "span_id": "span_789xyz",
+  "service": "payment-service",
+  "environment": "production"
+}
+```
+
+You might want to show only:
+* `timestamp`
+* `level`
+* `message`
+
+You can achieve this with the following format string `{ts:timestamp} {level} {message}`.
+`{ts:timestamp}` formats the timestamp field (Unix epoch) as an ISO 8601 date format while `{level}`
+and `{message}` display the specified fields as is.
+
+The formatted log would appear as:
+```
+2024-11-27T18:46:00Z ERROR Failed to process payment.
+```
+
+For reference docs, see:
+* [Format string syntax](format-struct-logs-syntax)
+* [Formatters](format-struct-logs-formatters)

docs/src/user-guide/format-struct-logs-syntax.md

@@ -0,0 +1,98 @@
+# Format string syntax
+
+Each format string is composed of:
+* [Static text](#static-text)
+* [Field placeholders](#field-placeholders)
+* [An implicit trailing newline](#implicit-trailing-newline)
+
+## Static text
+Static text may contain any character, except the following characters must be escaped with a
+backslash:
+* `{`
+* `}`
+* `\`
+
+## Field placeholders
+Each field placeholder is enclosed in braces (`{` and `}`) and has the following form, consisting of
+three components:
+```
+{<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 the following characters must be escaped with a
+  backslash:
+  * `.`
+  * `$`
+  * `{`
+  * `}`
+  * `:`
+  * `\`
+
+### formatter-name (optional)
+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 (` `), and the following characters 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 the following characters must be escaped with
+  a backslash:
+  * `{`
+  * `}`
+  * `:`
+  * `\`
+
+:::{note}
+`formatter-options` can only be specified if `formatter-name` was specified.
+:::
+
+## Implicit trailing newline
+
+Every format string contains an implicit trailing newline so that each formatted log event ends with
+a newline.
+
+## Examples
+Consider the following log event:
+```
+{
+  "@timestamp": 1427153388942,
+  "level": "INFO",
+  "thread": 0,
+  "latency": {
+    "msecs": 56400,
+    "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 `@timestamp`, 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 a nested 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-struct-logs-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
+Quick start
+^^^
+A guide to viewing log files in the log viewer.
+:::
+
+:::{grid-item-card}
+:link: format-struct-logs-overview
+Formatting structured logs
+^^^
+A guide to formatting structured (e.g. JSON) logs as plain text.
+:::
+
+:::{grid-item-card}
+:link: log-level-filtering
+Log level filtering
+^^^
+A guide to filtering log events by their levels.
+:::
+::::
+
+:::{toctree}
+:hidden:
+:caption: Quick start
+
+quick-start
+:::
+
+:::{toctree}
+:hidden:
+:caption: Formatting structured logs
+:glob:
+
+format-struct-logs-overview
+format-struct-logs-syntax
+format-struct-logs-formatters
+:::
+
+:::{toctree}
+:hidden:
+:caption: Log level filtering
+
+log-level-filtering
+:::

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

@@ -0,0 +1,15 @@
+# Overview
+
+The log viewer offers two ways to filter logs by their level.
+
+## Severity-based filtering
+You can filter for log events at or above a selected level by clicking the level's name. For
+example, selecting INFO shows INFO, WARN, ERROR, and FATAL logs.
+
+![Severity filtering](severity-filter.png)
+
+## Individual level filtering
+You can select specific log levels to show or hide by checking or unchecking the checkbox next to
+each level's name.
+
+![Individual level filtering](individual-filter.png)

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

@@ -0,0 +1,15 @@
+# Viewing logs
+
+The log viewer can open local or remote log files. The viewer currently supports viewing [CLP] IR
+and [JSONL] log files.
+
+## Opening local log files
+To open a local file, click the folder icon ({far}`folder`) in the top-left corner. This will open a file
+browser where you can navigate to and select the log file to open.
+
+## Opening remote log files
+To open a remote file, append `/?filePath=<FILE_URL>` to the current URL, replacing `<FILE_URL>`
+with the URL of your log file.
+
+[CLP]: https://github.com/y-scope/clp
+[JSONL]: https://jsonlines.org/