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; } }