Diagnostics and Logging
Relevant source files
The following files were used as context for generating this wiki page:The Pulsar Dome Driver incorporates a comprehensive diagnostics and logging system designed to provide detailed operational insight, facilitate debugging, and enable real-time monitoring. The system is built around a central FileLogger class, which provides persistent, thread-safe logging to a file. This is augmented by real-time messaging capabilities through MQTT and the Goodnight System (GNS), which broadcast critical status updates, warnings, and alarms.
The logging framework is highly configurable through the driver's settings, allowing users to control the log file location and verbosity (Debug/Trace levels). Various components, including the main driver logic, MQTT publisher, and action watchdogs, are integrated with the central logger to ensure a unified stream of diagnostic information. This multi-faceted approach ensures that developers and users have the necessary tools to monitor the driver's health and troubleshoot issues effectively.
Sources: Driver/Pulsar_DomeDriver.cs:115-132, Diagnostics/FileLogger.cs
Core Components
FileLogger Class
The FileLogger class is the cornerstone of the logging system. It handles writing timestamped log messages to a file in a thread-safe manner.
Sources: Diagnostics/FileLogger.cs
Architecture
The FileLogger is initialized with a file path and log level settings. It uses a StreamWriter to append messages to the log file and a lock on a private object (_writeLock) to prevent race conditions from multiple threads.
The diagram below illustrates the structure of the FileLogger class.
Diagram showing the main properties and methods of the FileLogger class.
Sources: Diagnostics/FileLogger.cs:7-20
Log Message Flow
When the Log() method is called, it first checks if the message's severity level is within the configured verbosity (_logLevel, _debugLog, _traceLog). If the check passes, it formats the message with a level label (e.g., "ERROR", "DEBUG") and passes it to the private WriteLine method. WriteLine adds a UTC timestamp and the managed thread ID before writing the final string to the log file inside a thread-safe lock.
The following flowchart shows the process of handling a log message.
Flowchart demonstrating the logic inside the FileLogger.Log method.
Sources: Diagnostics/FileLogger.cs:51-75
Log Levels
The verbosity of the logs is controlled by the LogLevel enum.
| Level | Value | Description |
|---|---|---|
None | 0 | No logging. |
Error | 1 | Logs only critical errors. |
Warning | 2 | Logs warnings and errors. |
Info | 3 | Logs informational messages, warnings, and errors. |
Debug | 4 | Logs detailed debugging information. |
Trace | 5 | Logs highly detailed trace information for execution flow. |
Sources: Config/ConfigManager.cs:5-13
WatchdogLogger
A secondary, static logger named WatchdogLogger exists for the specific purpose of logging watchdog-related activities. It writes to a hardcoded directory (D:\OneDrive\Documents\Logs) and is designed to fail silently to avoid crashing the watchdog if a logging error occurs.
Sources: MQTT/WatchDogLogger.cs
Configuration
Logging behavior is configured through the ASCOM profile, which is managed by the ConfigManager class and exposed to the user via the SettingsForm.
| Setting | Type | Description | UI Control | Source File |
|---|---|---|---|---|
LogLocation | string | The directory path where the log file is stored. | txtBoxLogLocation | Config/ConfigManager.cs:128 |
DebugLog | bool | Enables or disables Debug level logging. | chkBoxDebugLog | Config/ConfigManager.cs:220 |
TraceLog | bool | Enables or disables Trace level logging. | chkBoxTraceLog | Config/ConfigManager.cs:232 |
These settings are loaded and saved in SettingsForm.cs.
Sources: Config/ConfigManager.cs, UI/SettingsForm.cs:39-45, 81-86, UI/SettingsForm.Designer.cs:53, 54
System Integration
The FileLogger is instantiated in the DomeDriver's constructor and passed to other components, creating a centralized logging architecture.
This diagram shows how the FileLogger is shared across different parts of the application.
Component diagram showing the instantiation and dependency injection of FileLogger.
Sources: Driver/Pulsar_DomeDriver.cs:130, GNS/GNS.cs:20, MQTT/MqttPublisher.cs:22, Helper/ActionWatchdog.cs:50
Real-time Diagnostics
In addition to file logging, the driver uses MQTT and GNS for real-time diagnostic messaging.
MQTT Publishing
The MqttPublisher class sends messages to an MQTT broker on specific topics to report the driver's state. This is used for heartbeats, status changes, and critical alarms.
Key diagnostic topics include:
Dome/DriverStatus: General status messages like "Driver connected" or "Driver disconnected".Dome/Alarm: Used for unrecoverable errors, such as a failed hardware reset.Dome/Watchdog: Publishes a periodic heartbeat to indicate the driver is alive.Dome/Dome/Status: Publishes dome state changes.Dome/Shutter/Status: Publishes shutter state changes.
Sources: Driver/Pulsar_DomeDriver.cs:88-93, Driver/Pulsar_DomeDriver.cs:640-642, MQTT/MqttPublisher.cs
Goodnight System (GNS)
The GNS class provides another channel for notifications by sending messages to the "GNSBridge" named pipe. This is used to signal events to external monitoring tools.
Diagnostic GNSType messages:
Alarm: For critical failures, like a watchdog timeout or reset failure.Message: For general informational messages, like "Dome driver connected".Stop/Cease: To indicate the completion or termination of an action.
The sequence diagram below shows how an alarm is raised through both MQTT and GNS when a command fails.
Sequence of events when a command failure triggers GNS and MQTT alarm notifications.
Sources: GNS/GNS.cs:13-18, 26-42, Driver/Pulsar_DomeDriver.cs:1561-1568
Summary
The diagnostics system in Pulsar_DomeDriver is robust and multi-layered. It combines persistent file logging via FileLogger with real-time notifications through MQTT and GNS. This provides a comprehensive view of the driver's health, from high-level status updates to detailed trace logs for debugging. The system is configurable and well-integrated across all major components, making it a critical feature for ensuring reliable dome operation and simplifying troubleshooting.