---
source_files:
  - DataPRO/DbAPI/Logging/LogManager.cs
generated_at: "2026-04-16T04:26:52.712375+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "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*).