service-host-profiling 0.5.0__py3-none-any.whl

service_host_profiling/__init__.py

@@ -0,0 +1,27 @@
+"""Low-overhead Python Host spans and independent offline trace export."""
+
+__version__ = "0.5.0"
+
+from ._switch import is_enabled
+
+__all__ = [
+    "start", "stop", "span_start", "span_end", "profile", "is_enabled",
+    "attach_torch_profiler", "attach_sglang",
+]
+
+
+def __getattr__(name):
+    if name in {"start", "stop", "span_start", "span_end", "profile"}:
+        from . import collector
+        # Resolve lazy imports once. Repeated direct calls must not pay module
+        # __getattr__/import dispatch on every start and end.
+        value = getattr(collector, name)
+        globals()[name] = value
+        return value
+    if name == "attach_torch_profiler":
+        from .integrations.torch import attach_torch_profiler
+        return attach_torch_profiler
+    if name == "attach_sglang":
+        from .integrations.sglang import attach_sglang
+        return attach_sglang
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

service_host_profiling/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

service_host_profiling/_python_collector.py

@@ -0,0 +1,222 @@
+"""Opt-in, per-thread Python recording; JSONL is written only at stop()."""
+
+import functools
+import inspect
+import json
+import os
+from pathlib import Path
+import socket
+import threading
+import time
+import uuid
+
+_clock = time.perf_counter_ns if os.name == "nt" else time.monotonic_ns
+_local = threading.local()
+_lifecycle = threading.RLock()
+_active = None
+
+
+def _calibration():
+    before = _clock()
+    epoch = time.time_ns()
+    after = _clock()
+    return (before + after) // 2, epoch, after - before
+
+
+class _Buffer:
+    __slots__ = ("session", "tid", "records", "active")
+
+    def __init__(self, session):
+        self.session = session
+        self.tid = threading.get_native_id()
+        self.records = []
+        self.active = True
+
+
+class _Session:
+    def __init__(self, output_dir, session_id):
+        self.pid = os.getpid()
+        root = Path(output_dir).resolve()
+        root.mkdir(parents=True, exist_ok=True)
+        self.path = root / f"python_host_{self.pid}_{uuid.uuid4().hex}.jsonl"
+        self.session_id = session_id or self.path.stem
+        self.buffers = []
+        self.snapshots = []
+        self.registry = threading.Lock()
+        self.start = _calibration()
+        self.stop = None
+
+    def _accepted(self, record):
+        _, started, ended, _ = record
+        # Use the calibration bracket's upper bound, not its midpoint. A
+        # completion during stop calibration still belongs to the frozen data.
+        start_bound = self.start[0] - self.start[2] // 2
+        end_bound = self.stop[0] + (self.stop[2] + 1) // 2
+        return ended is not None and start_bound <= started <= ended <= end_bound
+
+    def _rows(self, tid, records):
+        for name, started, ended, attrs in records:
+            if not self._accepted((name, started, ended, attrs)):
+                continue
+            if not isinstance(name, str) or not name or "\0" in name:
+                raise ValueError("Span name must be a non-empty string without NUL")
+            if ended < started:
+                raise ValueError("Span end precedes start")
+            # Resolve deferred attributes only for accepted spans, after all
+            # thread buffers have been frozen. The recording path keeps the
+            # callable itself and never evaluates user code.
+            if callable(attrs):
+                attrs = attrs()
+            if attrs is not None and not isinstance(attrs, dict):
+                raise ValueError("Span attrs must be a JSON-serializable dict or None")
+            if attrs is not None:
+                attrs = {key: value() if callable(value) else value
+                         for key, value in attrs.items()}
+            yield {"pid": self.pid, "tid": tid, "name": name,
+                   "start_ns": started, "duration_ns": ended - started,
+                   "args": attrs if attrs is not None else {}}
+
+    def dump(self):
+        written = sum(self._accepted(record) for _, records in self.snapshots for record in records)
+        dropped = sum(not self._accepted(record) for _, records in self.snapshots for record in records)
+        metadata = {"schema_version": 3, "session_id": self.session_id,
+                    "pid": self.pid, "hostname": socket.gethostname(), "clock": "monotonic",
+                    "start_monotonic_ns": self.start[0] - self.start[2] // 2,
+                    "start_realtime_ns": self.start[1],
+                    "clock_uncertainty_ns": self.start[2], "written_spans": written,
+                    "dropped_spans": dropped,
+                    "stop_monotonic_ns": self.stop[0] + (self.stop[2] + 1) // 2,
+                    "stop_realtime_ns": self.stop[1], "complete": True}
+        pending = self.path.with_name(self.path.name + ".pending")
+        created = False
+        try:
+            with pending.open("x", encoding="utf-8", newline="\n") as output:
+                created = True
+                output.write(json.dumps({"type": "metadata", **metadata},
+                                        ensure_ascii=False, allow_nan=False,
+                                        separators=(",", ":")) + "\n")
+                span_id = 0
+                for tid, records in self.snapshots:
+                    for row in self._rows(tid, records):
+                        span_id += 1
+                        output.write(json.dumps({"type": "span", "id": span_id, **row},
+                                                ensure_ascii=False, allow_nan=False,
+                                                separators=(",", ":")) + "\n")
+                output.flush()
+                os.fsync(output.fileno())
+            # Same-directory exclusive publication of already flushed bytes.
+            # Never overwrite an existing JSONL or remove somebody's pending.
+            os.link(pending, self.path)
+        finally:
+            if created:
+                pending.unlink(missing_ok=True)
+            for buffer in self.buffers:
+                buffer.records.clear()
+                buffer.session = None
+            self.snapshots.clear()
+        return self.path
+
+
+def start(output_dir, *, session_id=None):
+    """Begin one process session. The returned path is complete only after stop()."""
+    global _active
+    with _lifecycle:
+        if _active is not None:
+            raise RuntimeError("Host collection is already active in this process")
+        if session_id is not None and (not isinstance(session_id, str) or not session_id):
+            raise ValueError("session_id must be a non-empty string")
+        _active = _Session(output_dir, session_id)
+        return _active.path
+
+
+def _register_thread():
+    session = _active
+    if session is None:
+        return None
+    with session.registry:
+        if session is not _active:
+            return None
+        buffer = _Buffer(session)
+        session.buffers.append(buffer)
+        _local.buffer = buffer
+        return buffer
+
+
+def span_start(name, attrs=None):
+    """Append [name, start_ns, end_ns, attrs]; return this thread's list span_id."""
+    buffer = getattr(_local, "buffer", None)
+    if buffer is None or not buffer.active:
+        buffer = _register_thread()
+        if buffer is None:
+            return -1
+    records = buffer.records
+    started = _clock()
+    # Stop can occur while the clock implementation runs. Recheck without a
+    # per-record lock; records begun outside the frozen window remain no-ops.
+    if not buffer.active:
+        return -1
+    span_id = len(records)
+    records.append([name, started, None, attrs])
+    return span_id
+
+
+def span_end(span_id):
+    """Set only the end timestamp; an span_id is valid only in its original thread/session."""
+    if span_id == -1:
+        return
+    buffer = getattr(_local, "buffer", None)
+    if buffer is None or not buffer.active:
+        return
+    ended = _clock()
+    if buffer.active:
+        buffer.records[span_id][2] = ended
+
+
+def stop():
+    """Freeze all thread buffers and synchronously publish one closed JSONL."""
+    global _active
+    with _lifecycle:
+        session = _active
+        if session is None:
+            raise RuntimeError("Host collection is not active")
+        with session.registry:
+            session.stop = _calibration()
+            _active = None
+            for buffer in session.buffers:
+                buffer.active = False
+            session.snapshots = [(buffer.tid, [tuple(record) for record in buffer.records])
+                                 for buffer in session.buffers]
+        return session.dump()
+
+
+def profile(name, attrs=None):
+    """Decorate a synchronous function with the same start/end pair."""
+    def decorate(function):
+        if (inspect.iscoroutinefunction(function) or inspect.isgeneratorfunction(function)
+                or inspect.isasyncgenfunction(function)):
+            raise TypeError("profile supports synchronous functions only")
+
+        @functools.wraps(function)
+        def wrapped(*args, **kwargs):
+            span_id = span_start(name, attrs)
+            try:
+                return function(*args, **kwargs)
+            finally:
+                span_end(span_id)
+
+        return wrapped
+
+    return decorate
+
+
+def _after_fork_child():
+    # Pure Python buffers must not be inherited as the child's active session,
+    # nor may inherited registry/lifecycle locks block its independent start.
+    global _active, _local, _lifecycle
+    _active = None
+    _local = threading.local()
+    _lifecycle = threading.RLock()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_after_fork_child)

service_host_profiling/_switch.py

@@ -0,0 +1,9 @@
+"""One process-wide choice, made before collection functions are imported."""
+import os
+
+ENABLED = os.environ.get("HOST_SERVICE_PROFILER_ENABLE") == "1"
+
+
+def is_enabled():
+    """Return the import-time choice; changing the environment needs a restart."""
+    return ENABLED

service_host_profiling/cli.py

@@ -0,0 +1,72 @@
+"""Offline export commands, usable without Torch or collection enabled."""
+
+import argparse
+import json
+import sys
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="service-host-profiling")
+    commands = ap.add_subparsers(dest="command", required=True)
+    export = commands.add_parser("export", help="Export closed Host JSONL or historical SQLite files")
+    export.add_argument("db", nargs="+")
+    export.add_argument("-o", "--output", required=True)
+    directory = commands.add_parser("merge-dir", help="Update every rank trace under one Torch capture root")
+    directory.add_argument("host_dir", help="Host capture directory containing closed JSONL files")
+    directory.add_argument("--torch-dir", required=True, help="Whole Torch capture directory above all rank outputs")
+    directory.add_argument("--pid-map", help='JSON object mapping Host OS PID to Torch Host PID')
+    directory_clock = directory.add_mutually_exclusive_group()
+    directory_clock.add_argument("--clock-offset-ns", help='Integer ns for one trace or JSON {"host_pid":offset_ns} for multiple ranks; omit to derive it from the vendor metadata beside each trace')
+    directory_clock.add_argument("--clock-anchors-ns", help='JSON pair for one trace or JSON {"host_pid":[[host0,target0],[host1,target1]]}; overrides automatic derivation')
+    args = ap.parse_args(argv)
+    try:
+        from pathlib import Path
+        from .parser import export_chrome_trace, merge_torch_directory
+        if args.command == "export":
+            result = export_chrome_trace(args.db, args.output)
+        else:
+            mapping = json.loads(args.pid_map) if args.pid_map else None
+            if mapping is not None and not isinstance(mapping, dict):
+                raise ValueError("--pid-map must be a JSON object")
+            if mapping is not None:
+                converted = {}
+                for key, value in mapping.items():
+                    if not key.isascii() or not key.isdecimal():
+                        raise ValueError("--pid-map keys must be decimal OS PIDs")
+                    pid = int(key)
+                    if pid in converted:
+                        raise ValueError("--pid-map contains duplicate PID spellings")
+                    converted[pid] = value
+                mapping = converted
+            host_root = Path(args.host_dir).expanduser().resolve(strict=True)
+            if not host_root.is_dir():
+                raise ValueError("HOST_DIR must be a Host capture directory")
+            hosts = sorted(host_root.rglob("*.jsonl"))
+            if not hosts:
+                raise ValueError(f"No closed Host JSONL files found under {host_root}")
+            def clock_value(raw, label):
+                if raw is None:
+                    return None
+                value = json.loads(raw)
+                if isinstance(value, dict):
+                    converted = {}
+                    for key, item in value.items():
+                        if not key.isascii() or not key.isdecimal():
+                            raise ValueError(f"{label} keys must be decimal Host OS PIDs")
+                        converted[int(key)] = item
+                    return converted
+                return value
+            offsets = clock_value(args.clock_offset_ns, "--clock-offset-ns")
+            anchors = clock_value(args.clock_anchors_ns, "--clock-anchors-ns")
+            result = merge_torch_directory(
+                hosts, args.torch_dir, pid_map=mapping,
+                clock_offset_ns=offsets, clock_anchors_ns=anchors)
+        if isinstance(result, list):
+            for path in result:
+                print(path)
+        else:
+            print(result)
+        return 0
+    except (ValueError, OSError, RuntimeError) as exc:
+        print(f"service-host-profiling: {exc}", file=sys.stderr)
+        return 1

service_host_profiling/collector.py

@@ -0,0 +1,30 @@
+"""Bind enabled or disabled Python functions once at import time."""
+from ._switch import ENABLED, is_enabled
+
+if ENABLED:
+    from . import _python_collector as _implementation
+    from ._python_collector import start, stop, span_start, span_end, profile
+
+    def __getattr__(name):
+        # Integration lifecycle checks need current state, not a copied value.
+        return getattr(_implementation, name)
+else:
+    _active = None
+    def span_start(name, attrs=None):
+        return -1
+
+    def span_end(span_id):
+        return None
+
+    def start(output_dir, *, session_id=None):
+        return None
+
+    def stop():
+        return None
+
+    def _identity(function):
+        return function
+
+    def profile(name, attrs=None):
+        # Returning the original callable eliminates a wrapper on every call.
+        return _identity

service_host_profiling/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional explicit integrations; no framework import at package import time."""

service_host_profiling/integrations/sglang.py

@@ -0,0 +1,179 @@
+"""Small explicit boundary for SGLang profile start/stop/export lifecycle.
+
+Install calls in each scheduler/worker process for each actual capture. Nothing
+imports or monkeypatches SGLang. Its own profiler still produces the Torch trace.
+"""
+
+from contextlib import closing
+from dataclasses import dataclass, field
+import hashlib
+import json
+import os
+from pathlib import Path
+import sqlite3
+import tempfile
+import time
+
+from .torch import TorchBinding, attach_torch_profiler
+from .._switch import ENABLED
+
+
+def _clock_sample():
+    """Bracket a Linux RAW sample in the database's MONOTONIC clock.
+
+    uncertainty_ns is the full bracket width, deliberately conservative.
+    Unsupported platforms record RAW=None; callers must calibrate explicitly.
+    """
+    # Use the exact clock selected by the Python collector on this platform.
+    sample_ns = time.perf_counter_ns if os.name == "nt" else time.monotonic_ns
+    before = sample_ns()
+    raw_clock = getattr(time, "CLOCK_MONOTONIC_RAW", None)
+    raw = time.clock_gettime_ns(raw_clock) if raw_clock is not None else None
+    after = sample_ns()
+    return {"monotonic_ns": (before + after) // 2,
+            "monotonic_raw_ns": raw, "uncertainty_ns": after - before,
+            "sample_before_ns": before, "sample_after_ns": after}
+
+
+def _pid_namespace():
+    namespace = Path("/proc/self/ns/pid")
+    try:
+        return os.readlink(namespace)
+    except OSError:
+        # This describes the available identity rather than inventing a host PID.
+        return f"unavailable:{os.name}:process-local-pid"
+
+
+def _closed_metadata(path):
+    if path.suffix == ".jsonl":
+        with path.open("r", encoding="utf-8") as stream:
+            return json.loads(stream.readline())
+    with closing(sqlite3.connect(path.as_uri() + "?mode=ro", uri=True)) as db:
+        return {key: json.loads(value) for key, value in
+                db.execute("SELECT key,value FROM metadata")}
+
+
+def _publish_manifest(path, document):
+    """Publish one complete sidecar atomically without replacing any file."""
+    descriptor, temporary = tempfile.mkstemp(prefix=".pending-", suffix=".json", dir=path.parent)
+    pending = Path(temporary)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as stream:
+            json.dump(document, stream, ensure_ascii=False, indent=2, allow_nan=False)
+            stream.write("\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        # A same-directory hardlink publishes fully written bytes exclusively;
+        # readers never observe an empty reservation or partially written JSON.
+        os.link(pending, path)
+    finally:
+        pending.unlink(missing_ok=True)
+
+
+@dataclass
+class SGLangCapture:
+    binding: TorchBinding
+    profile_id: str
+    rank: int | None = None
+    physical_device: int | None = None
+    source_version: object = None
+    clock_anchors: dict = field(default_factory=dict, init=False)
+    manifest_path: Path | None = field(default=None, init=False)
+    _stopped: bool = field(default=False, init=False)
+
+    @property
+    def db_path(self):
+        return self.binding.db_path
+
+    def start(self):
+        if not ENABLED:
+            return None
+        self.binding._check_process()
+        if self.binding.db_path is not None:
+            raise RuntimeError("Create a new capture for each profiling window")
+        self.clock_anchors["start_before"] = _clock_sample()
+        result = self.binding.start()
+        self.clock_anchors["start_after"] = _clock_sample()
+        return result
+
+    def stop(self):
+        """Stop/drain this rank's whole process collector, then return its DB.
+
+        Collection is process scoped. This refuses to stop another binding's
+        active collector. Use this method for the four-anchor archive workflow;
+        Use this owning-capture stop before archive; external stop cannot supply
+        all four clock samples needed for the manifest workflow.
+        """
+        if not ENABLED:
+            return None
+        self.binding._check_process()
+        if self._stopped:
+            return self.binding.db_path
+        from .. import collector
+        with collector._lifecycle:
+            active = collector._active
+            if active is None or self.binding.db_path is None or (
+                    active.path.resolve() != self.binding.db_path.resolve() or
+                    active.pid != self.binding.pid):
+                raise RuntimeError("This capture does not own the active process collector")
+            self.clock_anchors["stop_before"] = _clock_sample()
+            result = collector.stop()
+            self.clock_anchors["stop_after"] = _clock_sample()
+            if result.resolve() != self.binding.db_path.resolve():
+                raise RuntimeError("Stopped database does not match the owning capture")
+            self._stopped = True
+            return result
+
+    def archive(self, capture_root):
+        """Archive the closed DB and publish its rank manifest without a trace.
+
+        capture_root is explicit and must be under the attached output root.
+        Call stop() first. The returned path is the closed database;
+        manifest_path identifies its exclusive, atomically published sidecar.
+        The manifest filesystem must support same-directory hardlinks.
+        """
+        if not ENABLED:
+            return None
+        self.binding._check_process()
+        if not self._stopped:
+            raise RuntimeError("Call capture.stop() successfully before archive()")
+        root = Path(capture_root).resolve()
+        if not root.is_relative_to(self.binding.output_root):
+            raise ValueError("capture_root must be under the attached output root")
+        if root.is_relative_to(self.binding.output_root / ".host_trace"):
+            raise ValueError("capture_root cannot be the Host staging directory")
+        root.mkdir(parents=True, exist_ok=True)
+        path = self.binding.archive(root)
+        if self.manifest_path is not None:
+            return path
+        metadata = _closed_metadata(path)
+        if metadata.get("complete") is not True:
+            raise RuntimeError("Only complete closed databases may be published")
+        label = "unranked" if self.rank is None else f"rank-{self.rank}"
+        manifest = path.parent / f"{label}-{self.binding.session_id}.closed.json"
+        document = {"schema_version": 1, "type": "host_rank_archive", "complete": True,
+                    "profile_id": self.profile_id, "rank": self.rank,
+                    "session_id": self.binding.session_id,
+                    "db_relative_path": path.relative_to(root).as_posix(),
+                    "db_sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
+                    "hostname": metadata["hostname"], "pid": metadata["pid"],
+                    "pid_namespace": _pid_namespace(), "physical_device": self.physical_device,
+                    "source_version": self.source_version, "clock_anchors": self.clock_anchors}
+        _publish_manifest(manifest, document)
+        self.manifest_path = manifest
+        return path
+
+def attach_sglang(output_dir, *, profile_id, rank=None, physical_device=None,
+                  source_version=None):
+    """Bind one SGLang capture in its owning process; collection starts explicitly."""
+    if not isinstance(profile_id, str) or not profile_id:
+        raise ValueError("profile_id must be a non-empty SGLang capture identifier")
+    if rank is not None and (isinstance(rank, bool) or not isinstance(rank, int) or rank < 0):
+        raise ValueError("rank must be a non-negative integer or None")
+    if physical_device is not None and (isinstance(physical_device, bool) or
+            not isinstance(physical_device, int) or physical_device < 0):
+        raise ValueError("physical_device must be a non-negative integer or None")
+    # Snapshot external provenance; retain opaque JSON without a config system.
+    provenance = json.loads(json.dumps(source_version, allow_nan=False))
+    binding = attach_torch_profiler(output_dir)
+    return SGLangCapture(binding, profile_id, rank, physical_device, provenance)

service_host_profiling/integrations/torch.py

@@ -0,0 +1,111 @@
+"""Explicit Host raw-data binding alongside an existing Torch profiler.
+
+This module neither imports Torch nor starts, parses, or patches its profiler.
+The caller supplies each real capture directory and an already exported trace.
+"""
+
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+import shutil
+import tempfile
+import uuid
+
+from .._switch import ENABLED
+
+
+@dataclass
+class TorchBinding:
+    output_root: Path
+    session_id: str
+    pid: int = field(default_factory=os.getpid)
+    db_path: Path | None = field(default=None, init=False)
+    session_dir: Path | None = field(default=None, init=False)
+
+    @property
+    def output_dir(self):
+        return self.output_root / ".host_trace" / self.session_id
+
+    def _check_process(self):
+        if os.getpid() != self.pid:
+            raise RuntimeError("TorchBinding cannot be reused after fork; attach in each worker")
+
+    def start(self):
+        """Start Host collection before the concrete Torch directory exists."""
+        if not ENABLED:
+            return None
+        self._check_process()
+        if self.db_path is not None:
+            raise RuntimeError("This binding already owns a collection; create a new binding per capture")
+        from ..collector import start
+        self.db_path = Path(start(self.output_dir, session_id=self.session_id)).resolve()
+        return self.db_path
+
+    def archive(self, host_capture_dir):
+        """Archive a stopped Host JSONL within the caller's Host-data root."""
+        if not ENABLED:
+            return None
+        self._check_process()
+        target_dir = Path(host_capture_dir).resolve(strict=True)
+        if not target_dir.is_dir() or not target_dir.is_relative_to(self.output_root):
+            raise ValueError("Host capture directory must be under the Host output_root")
+        if target_dir.is_relative_to(self.output_root / ".host_trace"):
+            raise ValueError("Supply the Host capture directory, not the staging directory")
+        source = self.db_path
+        if source is None:
+            raise RuntimeError("No Host data is bound; call binding.start() first")
+        source = source.resolve(strict=True)
+        if self.session_dir is not None:
+            if self.session_dir != target_dir or source != self.db_path:
+                raise ValueError("This session is already finalized to another location")
+            return self.db_path
+        if not source.is_relative_to(self.output_dir.resolve()):
+            raise ValueError("Host data must belong to this binding's staging directory")
+        # Validate every row/count, not only a header claiming complete=true.
+        from ..parser import _databases
+        database = _databases(source)[0]
+        for _ in database.spans():
+            pass
+        metadata = database.metadata
+        if metadata.get("session_id") != self.session_id or metadata.get("pid") != self.pid:
+            raise ValueError("Host data process/session does not match this binding")
+        if metadata.get("complete") is not True:
+            raise RuntimeError("Stop Host collection successfully before archiving")
+        if source.suffix == ".db":
+            wal = Path(str(source) + "-wal")
+            if wal.exists() and wal.stat().st_size:
+                raise RuntimeError("Host DB has an outstanding WAL; close/checkpoint the collector before archiving")
+        host_dir = target_dir / "HOST_TRACE"
+        host_dir.mkdir(exist_ok=True)
+        destination = host_dir / source.name
+        descriptor, temporary = tempfile.mkstemp(prefix=".archive-", suffix=".pending", dir=host_dir)
+        pending = Path(temporary)
+        try:
+            with os.fdopen(descriptor, "wb") as output:
+                with source.open("rb") as incoming:
+                    shutil.copyfileobj(incoming, output)
+                output.flush()
+                os.fsync(output.fileno())
+            os.link(pending, destination)
+        except FileExistsError:
+            raise FileExistsError(f"Refusing to replace existing Host data: {destination}") from None
+        finally:
+            pending.unlink(missing_ok=True)
+        try:
+            source.unlink()
+        except BaseException:
+            destination.unlink(missing_ok=True)
+            raise
+        self.db_path = destination
+        self.session_dir = target_dir
+        return destination
+
+def attach_torch_profiler(output_root, *, session_id=None):
+    """Prepare an explicit per-worker, per-capture binding without starting Torch."""
+    root = Path(output_root).resolve()
+    token = session_id if session_id is not None else uuid.uuid4().hex
+    if not isinstance(token, str) or not token or len(token) > 128:
+        raise ValueError("session_id must be a non-empty string of at most 128 characters")
+    if any(not (c.isascii() and (c.isalnum() or c in "_-")) for c in token):
+        raise ValueError("session_id may contain only ASCII letters, digits, underscore and hyphen")
+    return TorchBinding(root, token)