diff --git a/src/content/user_guide/dashboard/sessions.md b/src/content/user_guide/dashboard/sessions.md index 717df6f..4f1fa04 100644 --- a/src/content/user_guide/dashboard/sessions.md +++ b/src/content/user_guide/dashboard/sessions.md @@ -1,37 +1,122 @@ -# Managing Sessions +=== "Managing Sessions" -Every run of your entrypoint is logged as a session, and the dashboard gives you tools to browse, organize, and clean up those sessions without touching the log files by hand. + # Managing Sessions -## Browsing + Every run of your entrypoint is logged as a session. The dashboard provides tools to browse, organize, inspect, and visualize those sessions without touching the underlying log files. -The **Overview** page lists every project with logged sessions. Open a project to see its individual sessions, or open a session directly to see its full logs and metadata. + ## Browsing -Each session has a status: + The **Overview** page lists every project with logged sessions. Open a project to see its individual sessions, or open a session directly to see its full logs and metadata. -- `running` — currently in progress -- `completed` — finished normally -- `failed` — finished with an error -- `crashed` — stopped writing without a proper close (e.g. the process died) + Each session has a status: -## Filtering + - `running` — currently in progress + - `completed` — finished normally + - `failed` — finished with an error + - `crashed` — stopped writing without a proper close (e.g. the process died) -From a project or the overview, sessions can be filtered by: + ## Filtering -- **Project** -- **Status** (`running`, `crashed`, `completed`, `failed`) -- **Date range** — sessions started after/before a given `YYYY-MM-DD HH:MM:SS` timestamp -- **Sort** — by start time, end time, duration, warning count, or exception count (ascending or descending) + From a project or the overview, sessions can be filtered by: -Archived sessions are hidden by default; toggle "include archived" to bring them back into the list. + - **Project** + - **Status** (`running`, `crashed`, `completed`, `failed`) + - **Date range** — sessions started after/before a given `YYYY-MM-DD HH:MM:SS` timestamp + - **Sort** — by start time, end time, duration, warning count, or exception count (ascending or descending) -## Renaming + Archived sessions are hidden by default; toggle **Include archived** to bring them back into the list. -Give a session a more memorable display name than its generated ID directly from the session or project view. The underlying `.fn` file and session ID are untouched - only the display name changes. + ## Renaming -## Archiving + Give a session a more memorable display name than its generated ID directly from the session or project view. The underlying `.fn` file and session ID are untouched—only the display name changes. -Archiving hides a session from the default view without deleting anything - useful for tidying up old or exploratory runs you want to keep around but not see day-to-day. Archived sessions can be restored at any time from the "include archived" view, which brings them back into the normal listing. + ## Archiving -## Deleting + Archiving hides a session from the default view without deleting anything, making it useful for tidying up old or exploratory runs you want to keep around but not see day-to-day. -Deleting a session removes it permanently. Unlike archiving, this cannot be undone - use archiving instead if you just want a session out of the way. + Archived sessions can be restored at any time from the **Include archived** view. + + ## Deleting + + Deleting a session removes it permanently. + + Unlike archiving, deletion cannot be undone. Use archiving instead if you simply want a session out of the way. + +=== "Metrics and Graphs" + + # Metrics and Graphs + + In addition to free-text log messages, fenn supports structured numeric metrics through `logger.log_metric()`. These metrics are stored alongside the session log and power the **Graphs** tab in the dashboard. + + ## Logging metrics + + ```python + from fenn.logging import logger + + logger.log_metric(name, value, step) + ``` + + Parameters: + + - `name` — identifies the metric. The dashboard currently recognizes and renders: + - `train_loss` + - `val_loss` + - `acc` + - `value` — numeric value to record + - `step` — x-axis position, typically the training epoch or iteration + + Example: + + ```python + for epoch in range(epochs): + train_loss = run_train_epoch(...) + logger.log_metric("train_loss", train_loss, step=epoch) + + if epoch % val_epochs == 0: + val_loss, acc = run_validation(...) + logger.log_metric("val_loss", val_loss, step=epoch) + logger.log_metric("acc", acc, step=epoch) + ``` + + ## Automatic metric logging + + The built-in trainers log metrics automatically during `fit()`: + + - `ClassificationTrainer` + - `RegressionTrainer` + - `LoRATrainer` + + These trainers record: + + - `train_loss` every training epoch + - `val_loss` and `acc` on validation epochs + + No additional logging code is required when using these trainers. + + ## Metric storage + + Each call to `log_metric()` appends a `` element to the session's `.fn` file: + + ```xml + + ``` + + Metrics are additive and independent of the free-text log entries stored in the same session. + + Sessions created before metric logging was introduced—or sessions that never call `log_metric()`—remain fully compatible. They simply contain no metric data. + + If `log_metric()` is called before the logger has been configured (for example, when using a trainer outside an `@app.entrypoint` execution), the call silently does nothing instead of raising an exception. + + ## Viewing graphs + + Open a session and switch from the **Logs** tab to the **Graphs** tab. + + While a session is still `running`, the Graphs tab displays a placeholder. Once the session finishes, the dashboard renders any available metrics as SVG line charts. + + Currently, three graphs are supported: + + - **Train Loss** + - **Validation Loss** + - **Accuracy** + + Sessions without metric data simply display an empty state in the Graphs tab. \ No newline at end of file diff --git a/src/css/extra.css b/src/css/extra.css index 5a46037..00b332d 100644 --- a/src/css/extra.css +++ b/src/css/extra.css @@ -318,3 +318,9 @@ article.md-content__inner { .md-footer-nav { margin-bottom: 3rem; } + +/* ── Tabbed Content ───────────────────────────────────────── */ + +.md-typeset .tabbed-content { + padding-top: 1.5rem; +}