Class Log
The application-wide logger, reached as a static facade from anywhere.
Inherited Members
Namespace: MOSAIC.Diagnostics
Assembly: MOSAIC.dll
Syntax
public static class Log
Remarks
Why a static facade and not an injected ILogger. Almost every diagnostic in this
app lives in a plain model class built by BlockFactory, not resolved from the DI
container. Threading a logger through those constructors would be a far larger change than the
logging itself, so the access route is a static and the cost of that decision is paid here: the
facade must be safe to touch from any thread, at any time, including before Avalonia exists.
What a call site costs. A disabled level is one Volatile.Read and a branch - the
interpolated-string handlers make the compiler skip the interpolation entirely (see
DebugLogHandler). An enabled level formats one string, takes one
Interlocked.Increment for the sequence number and does one non-blocking channel write.
No lock, no disk, no UI marshalling: all of that belongs to the sink's writer thread and to the
panel's own 30 fps pull.
Nothing here throws. A logger that faults while reporting a fault is worse than no logger, so every public entry point swallows, and the internal failure path only touches a counter and a string (InternalFailureCount, LastInternalError) rather than logging - otherwise a disk failure would recurse forever. Silence is not an option though: those two are what lets the panel say that the logger itself has stopped working.
Fields
EnvironmentLevelVariable
Declaration
private const string EnvironmentLevelVariable = "MOSAIC_LOG_LEVEL"
Field Value
| Type | Description |
|---|---|
| string |
InitGate
Declaration
private static readonly object InitGate
Field Value
| Type | Description |
|---|---|
| object |
PreInitBuffer
Declaration
private static readonly LogEntry[] PreInitBuffer
Field Value
| Type | Description |
|---|---|
| LogEntry[] |
PreInitCapacity
Entries kept aside while there is no file yet. Written to the file once one opens.
Declaration
private const int PreInitCapacity = 256
Field Value
| Type | Description |
|---|---|
| int |
PreInitFilled
Declaration
private static readonly int[] PreInitFilled
Field Value
| Type | Description |
|---|---|
| int[] |
SharedRing
Declaration
private static readonly LogRing SharedRing
Field Value
| Type | Description |
|---|---|
| LogRing |
_handlersInstalled
Declaration
private static int _handlersInstalled
Field Value
| Type | Description |
|---|---|
| int |
_initialized
Declaration
private static bool _initialized
Field Value
| Type | Description |
|---|---|
| bool |
_internalFailures
Declaration
private static long _internalFailures
Field Value
| Type | Description |
|---|---|
| long |
_lastInternalError
Declaration
private static string? _lastInternalError
Field Value
| Type | Description |
|---|---|
| string |
_minimumLevel
Declaration
private static int _minimumLevel
Field Value
| Type | Description |
|---|---|
| int |
_preInitCount
Declaration
private static int _preInitCount
Field Value
| Type | Description |
|---|---|
| int |
_preInitFlushed
Declaration
private static int _preInitFlushed
Field Value
| Type | Description |
|---|---|
| int |
_preInitOpen
Declaration
private static volatile bool _preInitOpen
Field Value
| Type | Description |
|---|---|
| bool |
_sequence
Declaration
private static long _sequence
Field Value
| Type | Description |
|---|---|
| long |
_sink
Declaration
private static LogFileSink? _sink
Field Value
| Type | Description |
|---|---|
| LogFileSink |
Properties
DefaultMinimumLevel
Declaration
private static LogLevel DefaultMinimumLevel { get; }
Property Value
| Type | Description |
|---|---|
| LogLevel |
DroppedCount
Entries discarded because the queue was full. Surfaced in the panel's toolbar.
Declaration
public static long DroppedCount { get; }
Property Value
| Type | Description |
|---|---|
| long |
InternalFailureCount
How many failures the logger has hit inside itself - a disk that filled up, a folder that was taken away, a writer that faulted.
Declaration
public static long InternalFailureCount { get; }
Property Value
| Type | Description |
|---|---|
| long |
Remarks
Counted in every configuration, not just Debug. The whole point of this subsystem is that a failure is visible to the student at the rig, and a logger that dies quietly is the exact bug it exists to prevent, so this is a supported UI signal: monotonic, allocation-free and safe to read at frame rate from any thread.
LastInternalError
Description of the most recent internal failure, or null while there has been none.
Declaration
public static string? LastInternalError { get; }
Property Value
| Type | Description |
|---|---|
| string |
LogDirectory
Folder the log files live in, or null when it could not be created.
Declaration
public static string? LogDirectory { get; private set; }
Property Value
| Type | Description |
|---|---|
| string |
LogFilePath
Full path of the file currently being written, or null when there is no file.
Declaration
public static string? LogFilePath { get; }
Property Value
| Type | Description |
|---|---|
| string |
MinimumLevel
The capture level: entries below it are never formatted, never queued and never seen.
Declaration
public static LogLevel MinimumLevel { get; set; }
Property Value
| Type | Description |
|---|---|
| LogLevel |
Remarks
Startup state - the build default plus the MOSAIC_LOG_LEVEL environment variable, both
applied by Initialize(). The panel's dropdown does not write it: that dropdown
filters the view over Ring, which retains its last Capacity
entries, so widening the filter brings back entries that were captured all along. Narrowing it
therefore never costs the file the context a bug report needs.
Ring
The bounded tail the in-app panel reads. Never null and usable before Initialize(), so an early entry is still visible once the panel opens.
Declaration
public static LogRing Ring { get; }
Property Value
| Type | Description |
|---|---|
| LogRing |
WriterStopped
True once the file writer has given up for good: the queue is no longer drained, so nothing further reaches the FILE until the next Initialize(). The ring and the panel keep working - Write(LogLevel, string, string?, string) treats a stopped writer as a refused entry and retains it in Ring instead.
Declaration
public static bool WriterStopped { get; }
Property Value
| Type | Description |
|---|---|
| bool |
Remarks
Exposed here so the panel can tell "the file is dead" apart from "nothing has been logged lately" without knowing the sink type. One volatile read, no allocation: safe to poll from the UI thread at frame rate. False while there is no file at all - the ring is then the whole logger and it is still working.
Methods
AppVersion()
Declaration
private static string AppVersion()
Returns
| Type | Description |
|---|---|
| string |
ApplyEnvironmentLevel()
Declaration
private static void ApplyEnvironmentLevel()
BufferPreInit(in LogEntry)
Keeps an entry logged before the file existed, so it is not missing from the file the student eventually sends. Lock-free by design: a producer must not start blocking just because the logger has not been initialised yet.
Declaration
private static void BufferPreInit(in LogEntry entry)
Parameters
| Type | Name | Description |
|---|---|---|
| LogEntry | entry |
CloseSink()
Declaration
private static void CloseSink()
Debug(string, ref DebugLogHandler)
Logs an interpolated per-packet detail; the interpolation is skipped when off.
Declaration
public static void Debug(string category, ref DebugLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| DebugLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Debug(string, string)
Logs a per-packet detail.
Declaration
public static void Debug(string category, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name, used as the bracketed prefix. |
| string | message | Already-built message. |
Debug(string, string?, ref DebugLogHandler)
Logs an interpolated per-packet detail for one named block instance.
Declaration
public static void Debug(string category, string? instance, ref DebugLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| DebugLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Debug(string, string?, string)
Logs a per-packet detail for one named block instance.
Declaration
public static void Debug(string category, string? instance, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| string | message | Already-built message. |
Describe(string, Exception)
Declaration
private static string Describe(string message, Exception ex)
Parameters
| Type | Name | Description |
|---|---|---|
| string | message | |
| Exception | ex |
Returns
| Type | Description |
|---|---|
| string |
Error(string, ref ErrorLogHandler)
Logs an interpolated error; the interpolation is skipped when off.
Declaration
public static void Error(string category, ref ErrorLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| ErrorLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Error(string, Exception, ref ErrorLogHandler)
Logs an interpolated failure with the exception appended.
Declaration
public static void Error(string category, Exception ex, ref ErrorLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| Exception | ex | Exception to append. |
| ErrorLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Error(string, Exception, string)
Logs a failure together with the exception's type, message and stack.
Declaration
public static void Error(string category, Exception ex, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| Exception | ex | Exception to append. |
| string | message | What was being attempted. |
Error(string, string)
Logs a failed operation.
Declaration
public static void Error(string category, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name, used as the bracketed prefix. |
| string | message | Already-built message. |
Error(string, string?, ref ErrorLogHandler)
Logs an interpolated error for one named block instance.
Declaration
public static void Error(string category, string? instance, ref ErrorLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| ErrorLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Error(string, string?, Exception, ref ErrorLogHandler)
Logs an interpolated failure for one named block instance, with the exception appended.
Declaration
public static void Error(string category, string? instance, Exception ex, ref ErrorLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| Exception | ex | Exception to append. |
| ErrorLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Error(string, string?, Exception, string)
Logs a failure for one named block instance, with the exception appended.
Declaration
public static void Error(string category, string? instance, Exception ex, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| Exception | ex | Exception to append. |
| string | message | What was being attempted. |
Error(string, string?, string)
Logs a failed operation for one named block instance.
Declaration
public static void Error(string category, string? instance, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| string | message | Already-built message. |
FlushCritical(TimeSpan)
Drains the queue and flushes the file on the CALLING thread, so the lines describing a crash
reach disk even when the writer task can no longer run. Gives up after
timeout. Never throws.
Declaration
public static void FlushCritical(TimeSpan timeout)
Parameters
| Type | Name | Description |
|---|---|---|
| TimeSpan | timeout | How long to wait for the file to become available. |
FlushPreInit(LogFileSink)
Writes what was logged before the sink opened into the new file, oldest first, preceded by a marker counting the entries this file will not contain. Called under InitGate; runs once.
Declaration
private static void FlushPreInit(LogFileSink sink)
Parameters
| Type | Name | Description |
|---|---|---|
| LogFileSink | sink |
Info(string, ref InfoLogHandler)
Logs an interpolated lifecycle event; the interpolation is skipped when off.
Declaration
public static void Info(string category, ref InfoLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| InfoLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Info(string, string)
Logs a lifecycle event.
Declaration
public static void Info(string category, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name, used as the bracketed prefix. |
| string | message | Already-built message. |
Info(string, string?, ref InfoLogHandler)
Logs an interpolated lifecycle event for one named block instance.
Declaration
public static void Info(string category, string? instance, ref InfoLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| InfoLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Info(string, string?, string)
Logs a lifecycle event for one named block instance.
Declaration
public static void Info(string category, string? instance, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| string | message | Already-built message. |
Initialize()
Opens the log file under %AppData%/MOSAIC/logs and installs the crash hooks.
Idempotent, never throws, and safe to call from any thread before Avalonia exists.
Declaration
public static void Initialize()
Initialize(string?)
As Initialize(), but writes into directoryOverride.
Declaration
public static void Initialize(string? directoryOverride)
Parameters
| Type | Name | Description |
|---|---|---|
| string | directoryOverride | Folder to log into, or null for the real |
InstallGlobalExceptionHandlers()
Routes process-level faults into the log so a crash in the shipped GUI build leaves a trace. Idempotent; called by Initialize().
Declaration
public static void InstallGlobalExceptionHandlers()
Remarks
The published binary is a Windows GUI subsystem executable with no console attached, so without this an unhandled exception vanishes without a word.
IsEnabled(LogLevel)
The whole level gate: one volatile read and a comparison, inlined into the caller.
Declaration
public static bool IsEnabled(LogLevel level)
Parameters
| Type | Name | Description |
|---|---|---|
| LogLevel | level | Level a call site is about to log at. |
Returns
| Type | Description |
|---|---|
| bool | True when the entry would be kept. |
NextSequence()
Hands out the next entry id. Used by the sink for the entries it synthesises.
Declaration
internal static long NextSequence()
Returns
| Type | Description |
|---|---|
| long |
NoteInternalFailure(string, Exception)
Records a failure inside the logger itself, which is never reported through the logger.
Declaration
internal static void NoteInternalFailure(string source, Exception ex)
Parameters
| Type | Name | Description |
|---|---|---|
| string | source | Which half failed, |
| Exception | ex | The failure. |
Remarks
A counter and a string, no queue and no file: this is the one path that must still work when the rest of the logger does not, and anything richer would risk re-entering it.
NoteInternalFailure(string, string)
Records a failure inside the logger using an already formatted description.
Declaration
internal static void NoteInternalFailure(string source, string detail)
Parameters
| Type | Name | Description |
|---|---|---|
| string | source | Which half failed, |
| string | detail | What went wrong. |
ReportInternalFailure(Exception)
Declaration
private static void ReportInternalFailure(Exception ex)
Parameters
| Type | Name | Description |
|---|---|---|
| Exception | ex |
ResolveDirectory(string?)
Declaration
private static string? ResolveDirectory(string? directoryOverride)
Parameters
| Type | Name | Description |
|---|---|---|
| string | directoryOverride |
Returns
| Type | Description |
|---|---|
| string |
Shutdown()
Flushes, stops the writer and closes the file. Idempotent, never throws.
Declaration
public static void Shutdown()
Warn(string, ref WarnLogHandler)
Logs an interpolated warning; the interpolation is skipped when off.
Declaration
public static void Warn(string category, ref WarnLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| WarnLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Warn(string, Exception, string)
Logs a recoverable problem together with the exception that caused it.
Declaration
public static void Warn(string category, Exception ex, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| Exception | ex | Exception to append. |
| string | message | What was being attempted. |
Warn(string, string)
Logs a recoverable problem.
Declaration
public static void Warn(string category, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name, used as the bracketed prefix. |
| string | message | Already-built message. |
Warn(string, string?, ref WarnLogHandler)
Logs an interpolated warning for one named block instance.
Declaration
public static void Warn(string category, string? instance, ref WarnLogHandler message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| WarnLogHandler | message | Interpolated message, evaluated only if the level is enabled. |
Warn(string, string?, Exception, string)
Logs a recoverable problem for one named block instance, with the exception appended.
Declaration
public static void Warn(string category, string? instance, Exception ex, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| Exception | ex | Exception to append. |
| string | message | What was being attempted. |
Warn(string, string?, string)
Logs a recoverable problem for one named block instance.
Declaration
public static void Warn(string category, string? instance, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| string | category | Component name. |
| string | instance | Block instance name, or null. |
| string | message | Already-built message. |
Write(LogLevel, string, string?, string)
Declaration
private static void Write(LogLevel level, string category, string? instance, string message)
Parameters
| Type | Name | Description |
|---|---|---|
| LogLevel | level | |
| string | category | |
| string | instance | |
| string | message |