The ComLogger component logs Fw::Com buffers (e.g., framed telemetry, events, or command packets) to files on the on-board filesystem. Each received Com buffer is written to the currently open log file, optionally prefixed with a 2-byte length field. Log files are timestamped and automatically rotated when they reach a configured maximum size, and a companion hash file is written on close for ground-side validation.
2. Requirements
Name
Description
Validation
SVC-COMLOGGER-001
The ComLogger component shall log the contents of Com buffers received on its comIn port
unit test
SVC-COMLOGGER-002
The ComLogger component shall optionally prefix each logged buffer with a 2-byte (U16) length field
unit test
SVC-COMLOGGER-003
The ComLogger component shall close the current file and open a new one when the configured maximum file size would be exceeded
unit test
SVC-COMLOGGER-004
The ComLogger component shall name log files using the configured prefix and the time of file opening
inspection
SVC-COMLOGGER-005
The ComLogger component shall write a hash (validation) file when closing each log file
unit test
SVC-COMLOGGER-006
The ComLogger component shall provide a command to close the currently open file
unit test
SVC-COMLOGGER-007
The ComLogger component shall report file errors via events
unit test
3. Design
The ComLogger is an active component. Com buffers arriving on the async comIn port are dispatched on the component's thread and written synchronously to the log file.
3.1 Port Description
Port
Kind
Type
Description
comIn
async input
Fw.Com
Com buffers to log
pingIn / pingOut
async input / output
Svc.Ping
Health ping
3.2 File Management
Log files are named <prefix>_<timeBase>_<seconds>_<microseconds>.com, using the component's time at file-open.
Files are opened lazily on the first received buffer and re-opened after rotation or a commanded close.
When storeBufferLength is enabled (the default), each buffer is preceded by its size as a U16; this permits ground tools to re-segment the log into individual packets.
When a write would exceed maxFileSize, the current file is closed and a new one opened.
On close, a companion hash file (<fileName><hash extension>) is written via Utils::Hash; failures produce FileValidationError.
Open and write errors are reported once per file via FileOpenError and FileWriteError to avoid event flooding.
3.3 Initialization
The component may be constructed either fully initialized — ComLogger(compName, filePrefix, maxFileSize, storeBufferLength) — or with the name-only constructor followed by a call to init_log_file(filePrefix, maxFileSize, storeBufferLength) before logging begins. Receiving data while uninitialized produces the throttled FileNotInitialized warning.
3.4 Commands
Command
Description
CloseFile
Force a close of the currently opened file, if any
3.5 Events
Event
Severity
Description
FileOpenError
warning high
Error opening a log file
FileWriteError
warning high
Error writing to a log file
FileValidationError
warning low
Error creating a validation (hash) file
FileClosed
diagnostic
A file was closed successfully on command
FileNotInitialized
warning low
Data received before initialization (throttled after 5 occurrences)
4. Usage
Instantiate the component in the topology and start its thread.
Initialize with a file prefix (which may include a directory path), maximum file size, and buffer-length storage option — either via the initializing constructor or init_log_file.
Connect the com stream to be logged (e.g., the downlink stream out of a framer or Svc::ComQueue) to comIn.
Close files on demand with the CloseFile command; files also close automatically on rotation and component destruction.