ChorusOS 5.0 Features and Architecture Overview

Trace Management

Trace management in the ChorusOS operating system is provided by the logging, black box, system dump, and core dump features.

Logging (`LOG` and `syslog`)

The LOG feature provides support for logging traces into a circular buffer on a target system. This feature has always been present in the ChorusOS operating system, and is retained for backward-compatibility reasons. A new, richer service called BLACKBOX has been introduced and has its equivalent in the Solaris operating environment (see "Black Box (BLACKBOX)").

The higher layers of the system also support a POSIX syslog facility. This service enables applications to write records that are marked with one of the possible predefined tags and a severity level. The records are sent to a syslog daemon that processes them according to a configuration file. Configuration of the daemon allows filtering of the records based on their tags and priority, and either appends them to a file, or sends them to a remote site. Records can also be ignored and discarded.

For details, see the LOG(5FEA) man page.

Logging API

The logging API is summarized in the following table:

Function	Description
`sysLog()`	Log a message in the circular buffer of the microkernel
`vsyslog()`	Write a log record (variable argument list)
`openlog()`	Open the log channel setting a default tag
`closelog()`	Close the log channel
`setlogmask()`	Set the priority mask level

In addition to the API, some other commands are provided:

Command	Description
`syslogd`	Daemon managing filtering and storing
`logger`	Write a message in a log
`syslogd.conf`	Configuration file for `syslogd`

Black Box (`BLACKBOX`)

The BLACKBOX feature provides an enhanced means for tracing and can be configured into or out of the system independently of the LOG feature.

The black box feature relies on multiple in-memory circular buffers that are managed by the system. One circular buffer is active at any time, which means that traces are added sequentially to that buffer. The buffer then wraps around when full. A buffer can be frozen through an explicit request indicating to the system which other buffer will be activated next. Records can be read from a frozen black box. Filtering control routines enables black box records to be discarded without the producer of such traces knowing about this filtering. Black box buffers are always part of the system dump in the case of a node failure leading to a dump.

The ChorusOS black box feature closely resembles the black box feature of the the Solaris operating environment.

For details, see BLACKBOX(5FEA).

Black Box API

The black box API common with the Solaris operating environment is summarized in the following table:

Function	Description
`bb_event()`	Write a record in the current black box
`bb_freeze()`	Freeze the current black box
`bb_list()`	Get the list and status of system black boxes
`bb_open()`	Open a frozen black box
`bb_read()`	Read the content of an open black box
`bb_close()`	Close an open black box
`bb_release()`	Unfreeze a frozen black box
`bb_getfilters()`	Retrieve current filters
`bb_setfilters()`	Set filters
`bb_getseverity()`	Retrieve severity level filter
`bb_setseverity()`	Set severity level filter
`bb_getprodids()`	Retrieve producer ID filter list
`bb_setprodids()`	Set producer ID filter list

The ChorusOS microkernel-specific API for BLACKBOX is as follows:

Function	Description
`bbEvent()`	Adds an event to the black box
`bbFreeze()`	Freezes the currently active black box and directs all future events to another black box
`bbRelease()`	Frees up a frozen black box
`bbSeverity()`	Gets and/or sets the global severity bitmap for the node
`bbGetNbb()`	Gets the number of black boxes configured on the node
`bbList()`	Gives information about the set of black boxes on the node
`bbFilters()`	Gets and/or sets the filter list and the filtered severity bitmap for the node
`bbProdids()`	Gets and/or sets the list of producers that have been registered to use the filter list and the filtered severity bitmap on this node
`bbOpen()`	Obtains access to a frozen black box
`bbClose()`	Releases access to a frozen black box
`bbReset()`	Resets a frozen black box
`bbName()`	Gets and/or sets the symbolic name of a persistent store used to hold the given black box

System Dump (`SYSTEM_DUMP`)

The system dump feature enables the system to collect data in case of a crash. In the ChorusOS operating system, data collection is defined as the content of the black box buffers. On system crash, these data are copied to a persistent memory area, or dump area, which is based on the HOT_RESTART feature of the ChorusOS operating system. The system is then hot-restarted so that the persistent memory area is preserved. This reboot operation gives control back to the ChorusOS bootMonitor, which initiates the transfer of collected data to a configurable local or remote location. Remote transfer is based on the TFTP protocol.

For details, see the SYSTEM_DUMP(5FEA) man page.

System Dump API

The SYSTEM_DUMP API is summarized in the following table:

Function	Description
`systemDumpCopy()`	Copy the black box and system information in the dump area
`systemDumpTransfer()`	Transfer the dump area to the storage location

Core Dump (`CORE_DUMP`)

The core dump feature allows offline, postmortem analysis of actors or processes that are killed by exceptions. This is performed in three steps:

Gathering the relevant information from the actor or process to be killed
Dumping the information into a core file on a stable storage medium
Reloading the core file on the host machine for analysis

The core file is generated in the case of a fatal exception, upon request from the debugging server or agent or upon request from any actor or process. The following information is collected in the core file:

The current threads and their characteristics, namely, all hardware and software registers, the scheduling characteristics, and the thread's name and ID
The actor or process name, ID, capability, and type
Dynamic and shared library informations, such as path names and relocation information
Memory regions in use

For details, see the CORE_DUMP(5FEA) man page.

Trace Management

Logging (LOG and syslog)