Class Log

The application-wide logger, reached as a static facade from anywhere.

Inheritance
Log
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 %AppData% location. A non-null value is a test seam and deliberately re-opens the sink even if the logger is already running, so a test never has to reach the developer's real application-data folder.

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, Log or sink.

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, Log or sink.

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

Search documentation

Start typing to search the documentation.