DP44/enriched-qwen3-coder-next/DataPRO/DbAPI/Logging.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DbAPI/Logging/LogManager.cs	2026-04-16T04:26:52.712375+00:00	Qwen/Qwen3-Coder-Next-FP8	1	93d08dfeda60c1f4

Logging

Purpose

This module provides centralized logging infrastructure for the DbAPI layer, abstracting the underlying logging mechanism (TextLogger) and exposing a simplified, type-safe interface for recording events with specific categories and severity levels. It ensures thread-safe initialization, enforces log level filtering, and writes all log entries to a rolling log file (DB.log) with standardized timestamping and formatting.

---

Public Interface

All members are internal (not public), per the internal class LogManager declaration. However, the module exposes the following static members accessible within the DbAPI.Logging namespace:

• public static Sink DBAPILogWriter
  A delegate of type Sink (from DTS.Common.Utilities.Logging) assigned during initialization to the LogMsg method. It serves as the external-facing write endpoint for log messages.

• public static void Initialize(int logSize, string path, int minLog)
  Initializes the logging system exactly once per application lifetime (idempotent due to early return if _LogWriter is non-null). Creates a TextLogger writing to {path}/DB.log, configures log rollover, sets the minimum log level (_MinLog), and assigns DBAPILogWriter.
  Parameters:

  • logSize: Maximum size (in bytes?) for the log file before rollover.
  • path: Directory path where DB.log will be written.
  • minLog: Bitwise combination of TraceEventType values (cast to int) defining the minimum severity to log (e.g., Error | Warning).

• public static void Log(TraceEventType eventType, LogEvents logEvent, string msg)
  Logs a message if the eventType meets or exceeds the configured _MinLog level (via bitwise AND check). Formats the message with a timestamp, event type, LogEvents category, and the provided msg, then writes it via LogMsg.
  Parameters:

  • eventType: Severity level (e.g., TraceEventType.Error, Information).
  • logEvent: Category from the LogEvents enum.
  • msg: The log message text.

• public static void OnWriteException(Exception ex)
  Callback invoked by TextLogger on write failures. Writes the exception message to Console.Error.

---

Invariants

• _LogWriter is initialized exactly once per AppDomain lifetime (enforced by lock + null-check in Initialize).
• Log messages are written only if (minLog & (int)eventType) == (int)eventType holds (i.e., the event type is included in the configured minimum log level).
• All log entries are prefixed with a fixed-format timestamp: yyyy-MM-dd HH:mm:ss.fff.
• The log file path is always {path}/DB.log.
• _MinLog is set during initialization and never modified afterward.
• DBAPILogWriter is assigned only during the first call to Initialize and remains non-null thereafter.

---

Dependencies

• Imports/Usings:
  • DTS.Common.Utilities.Logging (provides Sink, TextLogger, APILogger).
  • System, System.Diagnostics, System.IO.
• External Types Used:
  • DTS.Common.Utilities.Logging.TextLogger (core logging implementation).
  • DTS.Common.Utilities.Logging.APILogger (only referenced for Sink type via using static).
  • System.TraceEventType (severity levels).
• Depended Upon By:
  • Other classes in the DbAPI layer (inferred from namespace DbAPI.Logging and DBAPILogWriter usage).
  • Not directly consumed by external consumers (all members are internal).

---

Gotchas

• Thread Safety: Initialize uses a lock to prevent re-initialization, but Log and LogMsg are not explicitly synchronized. However, TextLogger is assumed to be thread-safe (typical for such utilities).
• Silent Failures: LogMsg catches and discards all exceptions during logging, potentially masking I/O errors (e.g., disk full, permission issues).
• Hardcoded Log Filename: The log file is always named DB.log, with no configurability.
• Log Level Semantics: _MinLog uses a bitwise mask against TraceEventType values. The default (Error | Warning) means Information, Verbose, etc., are excluded unless explicitly enabled.
• No Cleanup: No Dispose or shutdown logic is provided; resources (e.g., file handles) persist until process termination.
• Timestamp Format: Milliseconds are zero-padded to 3 digits, but no timezone info is included (local time only).
• Enum Naming: LogEvents is poorly named (implies events like "Connections", but actually represents categories or topics).