Logging

Trace Buffers

Trace buffers are circular, in-memory log buffers. They are typically used for collecting debug data, which can then be displayed in the CLI or dumped to a file. A process can have multiple trace buffers. It is typically convenient to use one for each component or library within a process.

To display a trace buffer in the CLI:

debug ems show trace <process> <bufname>|all

Trace buffers can be plugged into the Python logging module with a TraceBufferHandler:

from exos import api
import logging

logger = logging.getLogger("myapp")
logger.setLevel(logging.DEBUG)

logHandler = api.TraceBufferHandler("mybuf", 20480)
logHandler.setLevel(logging.DEBUG)
logger.addHandler(logHandler)

Trace buffers can also be used directly with the TraceBuffer class.

class exos.api.TraceBuffer(buffer_name, buffer_size)

A circular in-memory log buffer.

log(msg)

Log msg to the trace buffer

dump(file_name)

Dump this trace buffer to file_name. When file_name is None, the filename is generated. The file is always written under /usr/local/tmp.

clear()

Clear this trace buffer. All existing log entries will be deleted.

class exos.api.TraceBufferHandler(buffer_name, buffer_size)

A logging.Handler that’s backed by a TraceBuffer. Allows the standard Python logging mechanism to be used with trace buffers. buffer_name and buffer_size are used to create the TraceBuffer.

trace_buffer

__init__(buffer_name, buffer_size)

Create a new handler, backed by a trace buffer named buffer_name. TraceBufferAlreadyExistsError is thrown if the trace buffer has already been created.

emit(record)

Write record to the trace buffer.

exos.api.dump_trace_buffer(buffer_name, file_name)

Dump a trace buffer buffer_name to a file file_name. If buffer_name is None, then all buffers is dumped. If file_name is None, the file name will be generated. The trace buffer is written to /usr/local/tmp/<file_name>. If buffer_name is given, but does not exist, UnknownTraceBufferError is raised.

exos.api.clear_trace_buffer(buffer_name)

Clear a trace buffer buffer_name. If buffer_name is None, then all buffers are cleared. If buffer_name is given, but does not exist, UnknownTraceBufferError is raised.

System Log

An ExosLogger allows a Python process to log entries into the system log (i.e. show log). It integrates with the logging module so that the log messages can be directed to handlers as well.

Before an ExosLogger can be used, conditions must be added and it must be registered. For example:

elog=api.ExosLogger("example", "Example Logger", 1)
elog.add_condition("simple", "Just a simple message")
elog.add_condition("crit_cond", "Critical condition!", sev=api.Severity.CRITICAL)
elog.add_condition("could_not_open", "Unable to open %tgt% with %opt%", ["tgt", "opt"], sev=api.Severity.ERROR)
elog.register()

When registered, the conditions are actived as methods on the logger. To generate a log message, call the method with the required parameters:

elog.simple()
elog.crit_cond()
elog.could_not_open("somefile", "r")

ExosLoggers are LoggerAdapters, so Python logging methods are also supported. These messages will only be written to handlers, not to the system log:

elog.debug("About to open %s", "somefile")
elog.warning("Returning after error")

Detailed description of the ExosLogger class.

class exos.api.ExosLogger(name, title, format_version, content_version=1, component_id=None, factory_threshold='INFO', _internal_id=None)

An ExosLogger defines system log entries, such as those found in “show log”. As conditions are added to the ExosLogger, methods are added to log those conditions.

__init__(name, title, format_version, content_version, component_id, factory_threshold)

Create an ExosLogger and a Python Logger to back it. The Python Logger will use the name name.

title is an informational string, describing the logger.

format_version should be increased any time formatting of conditions in the ExosLogger is changed.

content_version should be increased any time conditions are added to the ExosLogger and formatting is not changed. Defaults to 1.

component_id is a unique number greater than 511 and less than 1024. If it is not provided, the name will be hashed to generate it. This is sufficient for most applications.

factory_threshold is the Severity level at which we’ll filter by default. Log messages below this level will be dropped, unless the threshold is overridden by configuration. By default, Severity.INFO.

register()

Register this ExosLogger with EXOS. After registering, the log conditions can be used and entries made in show log. However, conditions cannot be added after registering.

ready()

Return True if this ExosLogger has registered and is ready to log conditions.

add_condition(name, msg, params, sev)

Add a log condition to this ExosLogger. A LogComponentRegisteredError is raised if the ExosLogger has been registered. A method name is added to this logger for the new condition.

msg is the log message. It may contain parameters as “%foo%”.

params is an optional list of parameters to the condition. These must match names used in the msg.

sev is the severity of the condition. The default is Severity.WARNING.

EXOS severity levels. These will be mapped to Python logging severity levels as appropriate.

Severity.CRITICAL

Severity.ERROR

Severity.WARNING

Severity.NOTICE

Severity.INFO

Severity.DEBUG

Exceptions

class exos.api.UnknownTraceBufferError

Raised when an attempt is made to operate on an unknown trace buffer.

class exos.api.TraceBufferAlreadyExistsError

Raised when an trace buffer name is already in use.

class exos.api.LogComponentRegisteredError

Raised when an trace buffer name is already in use.