73 lines
4.7 KiB
Markdown
73 lines
4.7 KiB
Markdown
|
---
|
||
|
|
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*).
|