v4

Logging

This document describes the COSMOS logging framework and structure.

The COSMOS system creates a number of different logs both for data and for application events. The log file location is defined in the system.txt file by the ‘PATH LOGS’ setting. The log files which get created in this directory follow a common naming convention. The first part is a date and time: YYYYMM_DD_HH_MM_SS. This is followed by words specific to the COSMOS application. COSMOS applications produce the following logs:

Application Log File Name Description
Any <date>_exception.txt Exception file which is generated if a COSMOS application crashes. Any user provided interface code, background tasks, conversions, etc can result in an exception file if not properly written.
Any <date>_unexpected.txt Unexpected text output. If user code tries to print to the standard output using ‘puts’, this output is captured and an unexpected log file is created when the application exits.
Cmd/Tlm Server <date>_cmd.bin All outgoing command packets
Cmd/Tlm Server <date>_tlm.bin All incoming telemetry packets
Cmd/Tlm Server <date>_server_messages.txt All the server messages which are found in the bottom half of the Command and Telemetry Server application. Server messages are time stamped and categorized as INFO, WARN, or ERROR. Messages include red, yellow, limit violations, limit groups enable/disable, commands, and log file open/close.
Command Sender <date>_cmdsender_messages.txt Commands sent through Command Sender are logged and timestamped.
Script Runner <date>_sr_<filename>_messages.txt Each time a script is run, a new messages log file is created. This log captures any ‘puts’ output in the script as well as any user input. It also captures user interaction with Script Runner such as clicking the Pause and Stop buttons (as well as Step when debugging).
Test Runner <date>_sr_<test>_messages.txt Each time a test is run, a new messages log file is created. The <test> part of the filename is either the Suite name if a Suite is run, Suite_TestGroup if a Test Group is run, or Suite_TestGroup_TestCase if a test case is run. This log captures any ‘puts’ output in the script as well as any user input. It also captures user interaction with Script Runner such as clicking the Pause and Stop buttons (as well as Step when debugging).
Test Runner <date>_testrunner_results.txt Test Runner test report which indicates the file run, metadata, Test Runner settings (checkboxes), Test Case Results and a summary of the tests run.
Test Runner <date>_testrunner_results.zip If the Test Runner CREATE_DATA_PACKAGE configuration option is set, a zip file is created containing the the test report, the server messages and the command and telemetry bin files.

Binary File Structure

The Command and Telemetry Server binary log files contain command and telemetry packets. Each log file starts with a 128 byte header that is used internally by COSMOS to denote the version of definition files that were used when the file was created.

Item Data Type Description
Marker 8 byte ASCII String The ASCII string ‘COSMOS2*’
Type 4 byte ASCII String Either ‘CMD*’ for command logs or ‘TLM_’ for Telemetry logs
MD5 32 byte ASCII String 32 byte MD5 Sum calculated over the configuration files being used
Underscore 1 byte ASCII String An Underscore character
Hostname 83 byte ASCII String Left justified hostname of the computer that created the file

The file header is followed by command or telemetry packets (depending on the log type), each with a Big Endian header as follows. Note this is the same binary header used by the preidentified streaming protocol:

Item Data Type Description
Write Flags 8-bit unsigned integer 0x80 indicates whether the data is stored telemetry (see below). 0x40 indicates there is extra data following this byte. 0x3F bits are currently undefined. (since 4.3.0)
Extra Length (optional) 32-bit unsigned big endian integer Number of extra bytes (Optional, depends on Write Flags) (since 4.3.0)
Extra (optional) 32-bit unsigned big endian integer JSON encoded extra data (Optional, depends on Write Flags) (since 4.3.0)
Time Seconds 32-bit unsigned big endian integer Seconds since Unix epoch (Jan 1st, 1970 – Midnight)
Time Microseconds 32-bit unsigned big endian integer Microseconds of Second since Unix epoch (Jan 1st, 1970 – Midnight)
Target Name Length 8-bit unsigned integer Length in bytes of the target name
Target Name Variable length ASCII String String that indicates the name of the target that the data was sourced from.
Packet Name Length 8-bit unsigned integer Length in bytes of the packet name
Packet Name Variable length ASCII String String that indicates the name of the packet of data.
Packet Length 32-bit unsigned big endian integer Length in bytes of the packet
Packet Variable length block of data The binary data packet (endianness defined by packet definition)

The variable length nature of command and telemetry packets requires a log parser to start from the beginning of each log file when processing packets.

If the Write Flags indicate the data is stored telemetry (MSB set) COSMOS processes and stores the data in the telemetry log file but does not update the current value table. Thus stored telemetry does not affect displays or scripts.