Struct Session 

pub struct Session {
    pub id: String,
    pub output_dir: PathBuf,
    pub component: Arc<RwLock<Component>>,
    pub metrics_query: Mutex<Option<Arc<MetricsQuery>>>,
}

A workload run session.

The session is the root of the component tree and — once the runner has installed one — holds the shared MetricsQuery that every in-process reader (TUI, summary, Polydat metric nodes) reads through. See SRD-42 §“MetricsQuery — the unified read interface”.

Per SRD-77, the session is a persistent container; the Execution carried in [Self::execution] is the unit of in-flight work. Both ride on the component tree as the session + exec_id dimensional labels so every metric the descendant components emit inherits them.

Fields

id: String

Session identifier (the session-directory basename). Surfaces as the session dimensional label on every per-component metric via Self::component.

output_dir: PathBuf

Output directory for diagnostic artifacts (metrics, logs, flamegraphs). Located at logs/{id}/. Not the working directory.

component: Arc<RwLock<Component>>

Session root component — one per process (SRD-88 §2). Owns the session=<id> dimensional label and nothing else; per-execution identity (exec_id, workload) lives on the Execution::component children that hang under it. Each label name is owned by exactly one tier and never redeclared below it.

metrics_query: Mutex<Option<Arc<MetricsQuery>>>

Shared MetricsQuery handle — installed by the runner once the cadence reporter is built. None before the runner wires it.

Implementations

impl Session

pub fn new_with_args(session_name: &str, args: &[String]) -> Self

Create a new session. Picks the output directory in this priority order:

1. --session-dir <path> CLI flag (or SESSION_DIRECTORY env var, equivalent). SESSION token in the path is replaced with the auto-generated {session_name}_{timestamp} name. The basename becomes the session id.
2. --logs-dir <parent> and/or --session <name> CLI flags. Compose into <parent>/<name> (defaulting to logs/<auto-id> for any unspecified component).
3. Default — logs/{session_name}_{timestamp}/.

session_name is the auto-id stem (the single-run caller passes the scenario name; a concurrent SRD-88 host passes a session-level name). args is the raw CLI args slice — pass an empty slice to get env-only resolution. The session carries only session=<id> identity; per-execution workload/scenario live on the Execution tier.

pub fn new(session_name: &str) -> Self

Backward-compat shim for callers that don’t have CLI args handy. Equivalent to Session::new_with_args(session_name, &[]) — resolves session-dir from SESSION_DIRECTORY env only.

pub fn reattach(prior_session_dir: PathBuf, session_name: &str) -> Self

Re-attach to a prior session — reuse its directory, id, and (consequently) its metrics.db so the attaching invocation appends to the same metrics history rather than starting fresh in a new dir. Per SRD-44 §“Wholesale metrics-purge”, phases that re-run need their prior sample rows purged in-place; that requires writing to the same db, which requires reusing the same session dir. The id is read from the directory’s basename, so it preserves the original timestamp suffix.

Backs both nmbrs resume and nmbrs refine: the two differ only in the Execution the caller starts under this session (its verb and exec_id), which is now an execution-tier concern (SRD-88) — not a session-tier one. session_name is the fallback id stem used only when the directory basename can’t be read.

pub fn link_artifact(name: &str)

Create a logs/<artifact> convenience symlink that points (through logs/latest) at the named artifact in the current session’s output dir. Idempotent — replaces any existing link with the same name. Call from the writer at the moment the artifact has actually been produced, so the convenience link never dangles.

pub fn set_metrics_query(&self, query: Arc<MetricsQuery>)

Install the shared MetricsQuery handle. Called once by the runner after it has planned the cadence tree and built the cadence reporter. Panics if called twice.

pub fn metrics_query(&self) -> Option<Arc<MetricsQuery>>

Borrow the installed MetricsQuery. Returns None before the runner wires it.

pub fn metrics_path(&self) -> PathBuf

Path to the SQLite metrics file for this session.

pub fn profiler_path(&self, suffix: &str) -> PathBuf

Path for a profiler output file.

pub fn artifact_path(&self, filename: &str) -> PathBuf

Path for an arbitrary session artifact.