Module session 

Session: the root context for a workload run.

A session has a human-readable ID, a directory for all diagnostic artifacts (metrics, logs, flamegraphs), and is the root of the component tree for metrics labeling.

Session ID format: {scenario}_{YYYYMMDD_HHmmss} Session directory: logs/{session_id}/

All files from a run live under the session directory:

• metrics.db — SQLite metrics
• flamegraph.svg — profiler output
• session.log — diagnostic log (future)

Structs

Execution

SRD-77 — one invocation of nmbrs <verb> within a Session. The session is the persistent container; each execution is the unit of “what was attempted at this point in time, with what workload version, and how did it dispose?” Every per-phase / per-metric row carries the owning execution’s Self::exec_id as a dimensional label so cross-execution queries can scope cleanly.

Session

A workload run session.

SessionDirSpec

Resolved session inputs from CLI / env. Built by resolve_session_dir from one of:

Enums

SessionReuse

Policy when a session about to be created lands on an existing, non-empty session directory.

Constants

DEFAULT_SESSIONS_MAX

Default for --session-keep (alias --sessions-max): keep the 10 most-recent sessions, purging older ones at the start of the next session-creating command.

DEFAULT_SESSIONS_SHELFLIFE

Default for --session-shelflife (alias --sessions-shelflife): 4 weeks. Sessions older than this are purged regardless of the --session-keep cap.

SESSION_DIRECTORY_ENV

Legacy env-var name for --session-path. Pre-SRD-04 shipping name that some operators may have in their shell config; honored as a deprecated fallback below NMBRS_SESSION_PATH and warns when read.

SESSION_TOKEN

Token within a session-dir path that’s replaced with the auto-generated session id at write time. Lets users template per-run directories without changing the path between runs: --session-dir /data/sessions/SESSION_run → /data/sessions/default_20260101_120000_run.

Functions

args_request_dryrun

Whether the CLI args request a dry-run (any dryrun=<mode> with a non-empty, non-false value). A dry-run is resume-INERT: it must NOT claim the latest symlink and must NOT write a checkpoint, so a later --resume-latest can never pick a dry-run up and resume from its (placeholder / short-circuited) phases (SRD-44). Detected from raw args so both Session::new_with_args (the latest claim) and SessionHost::setup (the checkpoint writer) gate on one signal.

check_session_path

Classify a session-path value: does it look like a key=value workload-param token (e.g. scenario=foo) rather than a real filesystem path? The umbrella --session <kv> parser splits only on :, so a =-shaped token slipping into the path slot would silently materialise directories like <cwd>/scenario=foo/....

confine_to_dir

Resolve an operator-supplied relative path INSIDE base, refusing anything that could name a location elsewhere: an absolute path, a .. component, an empty path, or a Windows drive/prefix. Output paths that a workload file can set (metrics-log, trace_log) route through here, so a shared workload can only ever write into the session’s own directory tree.

count_session_dirs

Count directory entries under parent (excluding symlinks, files, and the latest symlink target). Used for end-of-run keep-cap forecasting.

default_session_dir

Where the default session directory lives when the user hasn’t passed --session-path. Three cases:

default_sessions_root

flag_env_name

Translate a CLI flag name (--session-path) into its canonical NMBRS_-prefixed env-var name (NMBRS_SESSION_PATH). Per SRD-04, every CLI flag automatically has an env-var equivalent following this convention.

forecast_keep_purge

Forecast how many session directories the next new session would auto-purge under parent given the current keep cap. Returns 0 when no purge would happen (or when keep_cap == 0, which disables the cap).

format_log_timestamp

Format a specific SystemTime in the same shape as now_log_timestamp. Used by the failure-dump path in nmbrs-tui::observer to render per-LogEntry timestamps captured at log-emit time.

format_utc_short

Convert days since Unix epoch to (year, month, day). Format Unix seconds as MM-DD HH:MM:SS (UTC).

init_empty_session

Initialize a NEW, empty session: create its directory, the metrics.db schema, and the invariant session metadata — but record NO execution (nothing has run). Points latest at it. A later run/refine attaches the first execution.

latest_checkpoint_jsonl

<root>/latest/checkpoint.jsonl — the SRD-44 event log of the most recent session. The resume planner reads from here.

latest_metrics_db

<root>/latest/metrics.db — the sqlite db of the most recent session. Centralised here so every read-side command names the path one way.

latest_session_dir

Resolve the parent directory the runtime treats as the session root when --session-path is absent. See default_session_dir for the three-case logic. <root>/latest — the symlink the runtime maintains to point at the most recent session dir. Read-side commands (nmbrs report, nmbrs plot, nmbrs replay, …) default to reading through this path so “show me my latest run” is the natural no-arg invocation.

latest_session_log

<root>/latest/session.log — the diagnostic log of the most recent session. nmbrs attach / log tooling reads from here.

now_log_timestamp

Current wall-clock time as YYYY-MM-DD HH:MM:SS.mmm (UTC). Used by the session log writer for human-readable line timestamps.

parse_duration

Parse a duration suffix-string. Accepts:

parse_session_kv

Parse the umbrella --session <kv-list> argument into a SessionDirSpec. The list is comma-separated; each item is either a bare shortcut (restart, resume, error) or a key:value pair.

point_latest_at

Point <sessions-root>/latest at session_dir, but only when the dir lives under the sessions root — a path the user redirected elsewhere (--session-path /tmp/x) is left alone, same guard as the startup hook. Best-effort: symlink failures warn rather than abort.

purge_stale_sessions

Purge stale session directories under parent according to max_sessions (keep the latest N) and shelflife (drop anything older than this).

purge_stale_sessions_at_startup

Run session-lifecycle cleanup at binary startup, honouring --session-keep / --session-shelflife.

read_session_dir

Resolve the --session / --session-path / --session-name arguments to a session directory path that metrics.db would live under. Used by every read-side tool (nmbrs plot, nmbrs report, nmbrs metrics ..., completion) so the same flag means the same thing everywhere.

resolve_active

Active-session resolver consolidating the patterns used by replay.rs / summary.rs / report_cmd.rs / metricsql_cmd.rs / plot_metrics.rs / completion.rs.

resolve_flag

Resolve a flag value from CLI args + its NMBRS_-prefixed env var. Returns None if neither is set. Exits with status 2 if BOTH are set — configuration conflict; we refuse to silently disambiguate.

resolve_session_dir

session_dir_has_prior_artifacts

Return true when dir exists AND contains artifacts that indicate a prior session’s state (metrics db, session log, or checkpoint). Used by Session::new_with_args to decide whether the reuse-policy check applies.

session_dir_named

<root>/<name> — a named session dir under the sessions root. Used by --session=<name> resolvers in read-side commands so the path doesn’t get spelled out at every call site.

utc_datetime_fields

UTC datetime components for session-name templating, derived from the same manual Gregorian math as [format_timestamp] (no chrono dependency). Returns (year, month, day, hour, minute, second, epoch_millis, epoch_seconds).