Table of Contents

Class TraceLocation

Namespace
Typhon.Engine
Assembly
Typhon.Engine.dll

Knows where a database's profiling captures live: {name}.typhon/profilings/ (#616, design D-1).

public static class TraceLocation
Inheritance
TraceLocation
Inherited Members

Remarks

Why co-location. Putting captures inside the bundle makes correlation structural — given a capture, its database is two levels up. The alternative is inferring the pairing from a fingerprint, and every inference step is a place to be subtly wrong later. Nothing else in the engine needs teaching about the directory: bundle handling never enumerates the root and rejects unknown entries (Typhon.Engine.Internals.PagedMMF only guards against a *file* occupying the bundle path), and WAL discovery is pattern-scoped, so a new subdirectory trips nothing.

⚠️ Co-location is not provenance. A capture sitting here proves it was written here, not that it matches what is here now — the bundle may have been copied, restored or migrated since. The identity recorded in the trace header (#614) and the drift readout remain required; this type only decides where files go.

Every path in the feature is derived here rather than by re-joining "profilings" at each call site.

Fields

ProfilingsDirectoryName

Subdirectory of the database bundle holding its profiling captures.

public const string ProfilingsDirectoryName = "profilings"

Field Value

string

SidecarSearchPattern

Glob matching the derived sidecar caches a viewer builds beside captures. Regenerable, so retention reclaims these first and never lets them compete with real captures for budget. The shape follows CacheFileExtension — the suffix is appended to the whole capture path, not substituted for its extension.

public const string SidecarSearchPattern = "*.typhon-trace-cache"

Field Value

string

TraceExtension

Extension of a capture file.

public const string TraceExtension = ".typhon-trace"

Field Value

string

Methods

CaptureOfSidecar(string)

The capture a sidecar was derived from — the inverse of SidecarOf(string). Returns sidecarPath unchanged when it does not carry the sidecar suffix.

public static string CaptureOfSidecar(string sidecarPath)

Parameters

sidecarPath string

Returns

string

IsCapture(string)

True when path names a capture rather than a sidecar or the policy file.

public static bool IsCapture(string path)

Parameters

path string

Returns

bool

Remarks

The sidecar suffix is appended to the whole capture name (x.typhon-trace → x.typhon-trace-cache), so a sidecar does not end with the capture extension and the first test already excludes it. The explicit second test is belt-and-braces against that convention changing to a substituted extension, where the two would become indistinguishable by suffix alone.

NewCapturePath(string, DateTime)

Path for a capture starting now, creating profilings/ if needed. The name is a UTC timestamp to the millisecond, which sorts lexicographically in chronological order — so a directory listing is already the right order for a profiles list, with no parsing.

public static string NewCapturePath(string bundleDirectory, DateTime startedUtc = default)

Parameters

bundleDirectory string

The database's {name}.typhon directory.

startedUtc DateTime

Capture start time; defaults to now. Injectable so tests are not timing-dependent.

Returns

string

ProfilingsDirectoryOf(string)

The profilings/ directory for a database bundle. Does not create it — see NewCapturePath(string, DateTime).

public static string ProfilingsDirectoryOf(string bundleDirectory)

Parameters

bundleDirectory string

The database's {name}.typhon directory.

Returns

string

SidecarOf(string)

The sidecar cache path for a capture. Delegates to GetCachePathFor(string) rather than re-deriving the convention: the builder and the reader already agree on it, and a pruner that computed the name a second way would silently miss real sidecars the day the convention moved.

public static string SidecarOf(string capturePath)

Parameters

capturePath string

Returns

string