using Serilog.Debugging;
namespace ZB.MOM.WW.OtOpcUa.Host.Logging;
///
/// Diagnostics for the "healthy process, silent log" failure mode: Serilog isolates per-sink
/// failures, so a file sink that cannot open or write its file leaves an empty log, a fully
/// functional server, and no visible signal anywhere. The failure is real — a sibling repo
/// reproduced it via handle contention on one path, where RollingFileSink logs the
/// lock-out to SelfLog and quietly falls through to the next name in sequence.
///
/// ⚠️ It is NOT, however, what the reported 0-byte production log turned out to be. That investigation concluded from
/// Get-ChildItem that production's log was 0 bytes for six weeks; opening the file showed
/// 4.66 MB of correct output. See for the Windows metadata
/// behaviour behind the false reading — the same trap this class must not fall into, since a
/// self-check's false positive reads as confirmation of the very bug it was added to find.
///
/// Two instruments close the genuine failure mode:
///
/// - — turns on Serilog's , the only
/// channel that sees the exceptions sinks swallow, writing to a dedicated file plus stderr.
/// - — after the startup banner, verifies each
/// configured file sink actually grew when an event was emitted, so a silently-failing
/// sink is reported at boot instead of discovered months later.
///
///
public static class LogPipelineDiagnostics
{
///
/// Relative to the current directory, which Program.cs anchors to the install dir before
/// calling this. Deliberately a fixed path rather than derived from the sink config: this is
/// the channel of last resort and must not depend on the configuration it is diagnosing.
///
internal const string SelfLogPath = "logs/serilog-selflog.txt";
///
/// A broken sink can fail on every event indefinitely (two SelfLog lines per event), so cap
/// the file by deleting an oversized one at boot rather than growing it across restarts.
///
private const long SelfLogRotateBytes = 5 * 1024 * 1024;
///
/// Enables Serilog SelfLog to and stderr. Failures reported here are
/// the ones sinks swallow — without this they are invisible by design. Never throws: a
/// diagnostics channel that can fail startup is worse than the defect it watches for; if the
/// file cannot be opened, stderr alone is used.
///
public static void EnableSelfLog()
{
StreamWriter? writer = null;
try
{
var dir = Path.GetDirectoryName(SelfLogPath);
if (!string.IsNullOrEmpty(dir))
Directory.CreateDirectory(dir);
var info = new FileInfo(SelfLogPath);
if (info.Exists && info.Length > SelfLogRotateBytes)
info.Delete();
writer = new StreamWriter(
new FileStream(SelfLogPath, FileMode.Append, FileAccess.Write, FileShare.Read))
{ AutoFlush = true };
}
catch
{
writer = null;
}
var gate = new object();
SelfLog.Enable(message =>
{
lock (gate)
{
try { writer?.WriteLine(message); } catch { /* channel of last resort — swallow */ }
try { Console.Error.WriteLine(message); } catch { /* ditto */ }
}
});
}
///
/// Verifies every config-driven Serilog file sink physically grew when
/// ran. Returns null when all sinks grew (or there is nothing checkable), else a warning
/// naming the silent template(s). The check measures total bytes across each template's
/// rolled-file family (logs/otopcua-.log → otopcua-*.log, which also covers the
/// _NNN collision-fallback names), so it is agnostic to rolling interval and to which
/// concrete file the sink is currently writing. Growth by a concurrent event counts as a pass —
/// the claim under test is "this sink's writes reach disk", not "our marker specifically landed".
///
/// The host configuration carrying Serilog:WriteTo.
/// Emits one event through the live pipeline (synchronous sinks flush before returning).
/// A warning describing the silent sink, or when the check passes.
public static string? CheckFileSinkGrowth(IConfiguration configuration, Action emitMarker)
{
try
{
var templates = new List();
foreach (var sink in configuration.GetSection("Serilog:WriteTo").GetChildren())
{
if (!string.Equals(sink["Name"], "File", StringComparison.Ordinal))
continue;
// A buffered sink legitimately defers bytes past the marker, so growth proves nothing
// either way — skip rather than false-alarm. (This host's config is unbuffered.)
if (string.Equals(sink["Args:buffered"], "true", StringComparison.OrdinalIgnoreCase))
continue;
var path = sink["Args:path"];
if (!string.IsNullOrWhiteSpace(path))
templates.Add(path);
}
if (templates.Count == 0)
return null;
var before = templates.Select(MeasureFamilyBytes).ToArray();
emitMarker();
var silent = templates.Where((t, i) => MeasureFamilyBytes(t) <= before[i]).ToList();
return silent.Count == 0
? null
: "Log-pipeline self-check FAILED: the Serilog file sink(s) at "
+ string.Join(", ", silent.Select(t => $"'{t}'"))
+ $" did not grow when a log event was emitted (cwd: {Directory.GetCurrentDirectory()})."
+ " The process will run but its log stays empty. Serilog swallows per-sink write"
+ $" errors; the actual reason is in SelfLog ({SelfLogPath}) and on stderr — read it"
+ " before acting, and confirm by OPENING the log file rather than by listing its"
+ " size, which on Windows reports the size-at-open while the sink holds the file.";
}
catch
{
// Never let the self-check take down or delay the host over a diagnostics defect.
return null;
}
}
///
/// Routes a self-check failure to the channels that do not depend on the broken pipeline:
/// the SelfLog output (file + stderr). Also emitted through the normal logger by the caller —
/// useless when the file sink is the broken part, but it reaches the console sink and any
/// OTel export.
///
/// The warning text to write.
public static void ReportFailure(string warning) => SelfLog.WriteLine("{0}", warning);
///
/// Total bytes across the template's file family. The family glob is prefix + "*" + extension
/// so otopcua-.log matches its own rolled (otopcua-20260811.log) and sequence
/// (otopcua-20260811_001.log) forms, and — because * matches zero characters —
/// the un-rolled name itself.
///
///
/// ⚠️ Length MUST be read through an opened stream, never from
/// (or Get-ChildItem/dir, which read the same place). On Windows the directory
/// entry's size and last-write time are not refreshed while the writing process holds the file
/// open, so a perfectly healthy log that the sink is actively appending to reports its
/// size-at-open — typically 0, with LastWriteTime == CreationTime — for the entire life
/// of the handle. Measuring that way makes this check declare every healthy sink silent at
/// boot: instrumentation that manufactures the exact failure it exists to detect. It also
/// produced the false 0-byte reading that made that report look like a six-week production
/// logging outage when the file in fact held 4.66 MB of correct output.
///
/// is required to open the file at all while the sink holds
/// its write handle; keeps this read from blocking a concurrent
/// roll or retention delete.
///
private static long MeasureFamilyBytes(string pathTemplate)
{
var dir = Path.GetDirectoryName(pathTemplate);
if (string.IsNullOrEmpty(dir))
dir = ".";
if (!Directory.Exists(dir))
return 0;
var pattern = Path.GetFileNameWithoutExtension(pathTemplate) + "*" + Path.GetExtension(pathTemplate);
long total = 0;
foreach (var file in Directory.EnumerateFiles(dir, pattern))
{
try
{
using var stream = new FileStream(
file,
FileMode.Open,
FileAccess.Read,
FileShare.ReadWrite | FileShare.Delete);
total += stream.Length;
}
catch (IOException) { /* rolled away mid-scan, or momentarily unshareable */ }
catch (UnauthorizedAccessException) { /* not ours to read — treat as unmeasurable */ }
}
return total;
}
}