Logging

The Interposer can write a detailed access log showing every file, registry, network, identity, plugin, and rich presence operation it intercepts. This log is useful for diagnosing redirect problems, discovering what paths a game uses, and verifying that virtual registry entries are being served correctly.

Enabling the Log

Configure logging in the Logging section of .interposer\Config.yml:

Logging:
  Files: true
  Registry: true
  Downloads: true
  Plugins: false
  Identity: false
  RichPresence: false
  DnsRedirects: true
  Network: false
  Level: Info

Key	Type	Default	Description
`Files`	bool	`false`	Log file open, attribute, enumeration, delete, move, copy and DLL-load operations.
`Registry`	bool	`false`	Log registry open, read, write, and delete operations.
`Downloads`	bool	`true`	Log file downloads from FastDL.
`Plugins`	bool	`false`	Log plugin load, unload, error, and config registration events.
`Identity`	bool	`false`	Log identity override operations (GetUserName, GetComputerName hooks).
`RichPresence`	bool	`false`	Log rich presence field changes, update pushes, and clears.
`DnsRedirects`	bool	`true`	Log DNS redirect matches. Enabled by default because DNS redirects are deliberate user-configured actions.
`Network`	bool	`false`	Log socket connections, DNS lookups, and network adapter enumeration.
`DirectInput`	bool	`false`	Log DirectInput object and device creation, enumeration, and interface aliasing. At `Debug` also lists every device an enumeration found and every device the filter hid.
`OsVersion`	bool	`false`	Log the Windows version reported to the game, and which API each caller used to ask for it. Each entry point is reported only the first time it is called.
`Level`	choice	`Info`	Verbosity within the subsystems enabled above. One of `Info`, `Debug`, `Trace`.

Log Level

The per-subsystem flags above decide which subsystems log. Level decides how much each one says. Unrecognized values fall back to Info.

Level	Adds
`Info`	Nothing — access lines only. This is the historical output.
`Debug`	Redirect diagnostics: whether a redirect rule fired, and whether a registry key was served from the virtual store or passed through to the real registry.
`Trace`	Everything in `Debug`, plus one line per file redirect rule evaluated and rejected.

Diagnostic lines are gated by both settings. [REDIRECT MISS] requires Files: true and Level: Debug; the registry diagnostics require Registry: true and Level: Debug.

Debug is verbose

At Debug, every file operation that does not match a redirect rule produces an extra [REDIRECT MISS] line. That is the point — it shows you the exact paths a game asks for, so you can write rules against them — but the log grows quickly. Set it back to Info once your rules work.

Diagnostic lines are written to the session log only. Unlike the access verbs, they are not delivered to plugins or to the .NET event stream.

Logs are written automatically to .interposer\Logs\<timestamp>.log — one file per session, no path configuration required. Each session log begins with a header:

# === Session started 2025-03-14 12:00:00 ===

Log Format

Each line follows this structure:

YYYY-MM-DD HH:MM:SS  [VERB]  <path>  [->  <redirected-path>]

The -> portion only appears when a path was changed — for example, when a file redirect matches or a FastDL file is served from the overlay cache.

Log Verbs

File Operations

Verb	Meaning
`[FILE READ]`	A file was opened for reading via `CreateFileW/A` or `CreateFile2`.
`[FILE WRITE]`	A file was opened for writing via `CreateFileW/A` or `CreateFile2`.
`[FILE R/W]`	A file was opened for both reading and writing.
`[FILE ATTR]`	`GetFileAttributesW/A` or `GetFileAttributesExW/A` was called on a path.
`[FILE REDIRECT]`	A file open or attribute query was redirected by a rule. The line shows the original path and the destination path separated by `->`.
`[FILE FIND]`	`FindFirstFileW/A` or `FindFirstFileExW/A` was called on a path.
`[FILE DELETE]`	A file was deleted via `DeleteFileW/A`.
`[FILE MOVE]`	A file was moved or renamed via `MoveFileW/A` or `MoveFileExW/A`.
`[FILE COPY]`	A file was copied via `CopyFileW/A` or `CopyFileExW/A`.
`[DLL LOAD]`	A DLL was loaded via `LoadLibraryW/A` or `LoadLibraryExW/A`.
`[FILE OVERLAY]`	A file open was served from the FastDL overlay cache instead of the game directory.
`[FILEREDIRECT]`	A `FileRedirects` configuration warning: an unresolved `%TOKEN%` in a pattern, or a rule skipped for a malformed regex. Written once at startup regardless of `Logging.Files`, because a rule that never loads is otherwise invisible.

Redirect Diagnostics

Only written at Level: Debug or higher, and only for a subsystem that is already enabled.

Verb	Level	Meaning
`[REDIRECT HIT]`	Debug	A `FileRedirects` rule matched. The line shows the source path and, after the `->`, the 1-based rule number and its pattern. When the pattern contained a `%TOKEN%`, the rule as written follows in parentheses.
`[REDIRECT MISS]`	Debug	No rule matched this path. The line shows either `no rules configured` or how many rules were evaluated.
`[REDIRECT RULE]`	Trace	One line per redirect pattern that was evaluated and rejected, for working out why a regex did not match.
`[REG HIT]`	Debug	The key was found in the virtual registry, so the request is served from the `.reg` store. Under `Registry.Isolated` the reason reads `served from virtual store (isolated)`, meaning the key was virtualized because isolation is on rather than because a file names it.
`[REG MISS]`	Debug	The key was passed through to the real registry, with the reason — `not in virtual space`, `handle not resolvable`, or `virtual key not in store`. `handle not resolvable` now means the handle came from outside the `Reg*` API entirely (a direct `ntdll` call), since any real open key is resolved through `NtQueryKey`.
`[REG PARTIAL]`	Debug	The key exists in the virtual store but the requested value name does not. The game receives `ERROR_FILE_NOT_FOUND` and there is no fallback to the real registry.
`[REG FLUSH]`	Debug	A `RegFlushKey` call. Every virtual write is persisted as it happens, so on a virtual key this only reports whether anything was still pending.
`[REG NOTIFY]`	Debug	A `RegNotifyChangeKeyValue` registration. On a virtual key it is accepted and the event is never signalled — nothing outside the process can change the store.
`[REG COPY]`	Debug	A `RegCopyTree` where either side is virtual, source `->` destination. The copied values are not logged individually; a tree copy would flood the log and the plugin callbacks.
`[REG LAYER]`	Debug	One line per `.reg` file in `Registry.Files` as it loads, marked `read-only` or `writable`. An extra line reports that `Registry.Isolated` is on.

[REG PARTIAL] is worth calling out: it is the signature of a Registry.reg that has the right key but is missing a value the game reads. At Info level this looks like an ordinary successful [REG READ].

FastDL Operations

Verb	Meaning
`[FASTDL]`	A file was checked against or downloaded from the FastDL server. The path shows the URL and the local destination separated by `->`.

Plugin Operations

Verb	Meaning
`[PLUGIN LOAD]`	A plugin DLL or ASI was loaded successfully.
`[PLUGIN ERROR]`	A plugin failed to load. The line includes the Win32 error code.
`[PLUGIN CONFIG]`	A plugin registered default configuration via `InterposerRegisterPluginConfig`.

Identity Operations

Verb	Meaning
`[IDENTITY]`	An identity override was applied or a hooked `GetUserName`/`GetComputerName` call returned the configured override value.

OS Version Operations

Verb	Meaning
`[OSVERSION]`	The version being reported to the game, written once at startup, and then once per entry point the first time the game calls it. Also carries configuration warnings, such as an unrecognized `OsVersion.Version`, which are written regardless of the flag.

Rich Presence Operations

Verb	Meaning
`[RP INIT]`	A rich presence backend connected successfully.
`[RP SET]`	A presence field was updated by a plugin (details, state, image, etc.).
`[RP UPDATE]`	Presence changes were pushed to all backends.
`[RP CLEAR]`	Presence was reset to config defaults.

Network Operations

Verb	Meaning
`[CONNECT]`	A socket connected to a remote host. The line shows the host (or IP literal) and the port.
`[DNS REDIRECT]`	A `DnsRedirects` rule matched a hostname lookup and substituted a replacement. The line shows the original and substituted hostnames separated by `->`. Gated by `Logging.DnsRedirects` (not `Logging.Network`).
`[ADAPTER ENUM]`	The game enumerated network adapters. The line shows which API it used: `GetAdaptersInfo`, `GetAdaptersAddresses`, or `WSAIoctl SIO_GET_INTERFACE_LIST`.
`[ADAPTER HIDE]`	A `NetworkAdapters` filter removed an adapter from an enumeration. The line shows the adapter's friendly name or description.

Registry Operations

Verb	Meaning
`[REG OPEN]`	A registry key was opened via `RegOpenKeyExW/A`.
`[REG CREATE]`	A registry key was opened or created via `RegCreateKeyExW/A`.
`[REG READ]`	A registry value was queried via `RegQueryValueExW/A`.
`[REG WRITE]`	A registry value was written via `RegSetValueExW/A`.
`[REG DELETE]`	A registry key or value was deleted.
`[REG ENUM]`	Registry subkeys or values were enumerated.
`[REG QUERY]`	Key metadata was queried via `RegQueryInfoKeyW/A`.

Always-On Events

These events are always written regardless of logging flags:

Verb	Meaning
`[HOOK INIT]`	A MinHook hook was installed. Shows the module, function name, and status.

Example Log Output

# === Session started 2025-03-14 12:00:00 ===
2025-03-14 12:00:01  [HOOK INIT]       advapi32!RegOpenKeyExW
2025-03-14 12:00:01  [IDENTITY]        Username override: PlayerOne
2025-03-14 12:00:01  [PLUGIN LOAD]     C:\Games\MyGame\.interposer\Plugins\CDKey.dll
2025-03-14 12:00:01  [PLUGIN CONFIG]   Registered defaults for CDKey
2025-03-14 12:00:01  [FILE READ]       C:\Games\MyGame\config.cfg
2025-03-14 12:00:01  [FILE REDIRECT]   C:\Games\MyGame\Saves\profile.dat  ->  C:\Users\Pat\AppData\Roaming\MyGame\Saves\profile.dat
2025-03-14 12:00:02  [REG OPEN]        HKEY_LOCAL_MACHINE\SOFTWARE\MyGame\1.0
2025-03-14 12:00:02  [REG READ]        HKEY_LOCAL_MACHINE\SOFTWARE\MyGame\1.0\PlayerName
2025-03-14 12:00:02  [DNS REDIRECT]    master.gamespy.com  ->  master.local
2025-03-14 12:00:02  [IDENTITY]        GetUserNameW -> PlayerOne
2025-03-14 12:00:03  [RP SET]          Details: Playing on de_dust2
2025-03-14 12:00:03  [RP UPDATE]       Details=Playing on de_dust2  State=Score: 7 - 3
2025-03-14 12:00:03  [FASTDL]          http://fastdl.lan/baseq3/maps/q3dm1.bsp  ->  C:\Games\Quake3\.interposer\Downloads\baseq3\maps\q3dm1.bsp

With Level: Debug, the same session additionally shows what the Interposer decided:

2025-03-14 12:00:01  [REDIRECT MISS]   C:\Games\MyGame\config.cfg  ->  2 rules, none matched
2025-03-14 12:00:01  [REDIRECT HIT]    C:\Games\MyGame\Saves\profile.dat  ->  rule #1  C:\\Games\\MyGame\\Saves\\(.+)
2025-03-14 12:00:02  [REG HIT]         HKEY_LOCAL_MACHINE\SOFTWARE\MYGAME\1.0  ->  served from virtual store
2025-03-14 12:00:02  [REG PARTIAL]     HKEY_LOCAL_MACHINE\SOFTWARE\MYGAME\1.0  ->  value not in store: RESOLUTION
2025-03-14 12:00:02  [REG MISS]        HKEY_CURRENT_USER\SOFTWARE\OTHERAPP  ->  not in virtual space

Using Logs to Diagnose Problems

Finding what paths a game uses: Enable Files: true, run the game briefly, then search the log for paths that look like save directories, config files, or hard-coded installation paths.

Checking if a redirect fired: Set Level: Debug and look for [REDIRECT HIT] / [REDIRECT MISS]. A hit names the rule number and pattern that matched; a miss shows the exact path that nothing matched, which is what you want to write your next pattern against. At Trace, each [REDIRECT RULE] line shows a pattern that was tried and rejected for that path.

Verifying virtual registry: Enable Registry: true. At Info, a [REG READ] line only confirms the hook is active — it looks the same whether the value came from .interposer\Registry.reg or the real registry. Set Level: Debug to tell them apart: [REG HIT] means the virtual store served it, [REG MISS] means it passed through, and [REG PARTIAL] means the key was virtual but the value was missing, so the game got ERROR_FILE_NOT_FOUND.

Debugging plugin issues: Enable Plugins: true to see whether plugins loaded, what errors occurred, and whether config registration succeeded.

Checking identity overrides: Enable Identity: true to confirm that GetUserName and GetComputerName calls are returning the configured values. The log shows every invocation of the hooked functions.

Registry key paths are uppercased in the log to normalize comparisons. This is expected behavior.

Enabling the Log​

Log Level​

Log Format​

Log Verbs​

File Operations​

Redirect Diagnostics​

FastDL Operations​

Plugin Operations​

Identity Operations​

OS Version Operations​

Rich Presence Operations​

Network Operations​

Registry Operations​

Always-On Events​

Example Log Output​

Using Logs to Diagnose Problems​