.. _logging:
.. module:: exos.api

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 :py:mod:`logging` module with a
:class:`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 :class:`TraceBuffer` class.

.. autoclass:: TraceBuffer
   
   .. automethod:: log
   .. automethod:: dump
   .. automethod:: clear

.. autoclass:: TraceBufferHandler

   .. autoinstanceattribute:: trace_buffer
     :annotation:

   .. automethod:: __init__
   .. automethod:: emit

.. autofunction:: dump_trace_buffer

.. autofunction:: clear_trace_buffer


System Log
------------------------------------------------

An :class:`ExosLogger` allows a Python process to log entries into the system
log (i.e. show log).  It integrates with the :mod:`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.

.. autoclass:: ExosLogger

   .. automethod:: __init__
   .. automethod:: register
   .. automethod:: ready
   .. automethod:: add_condition


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

.. data:: Severity.CRITICAL
.. data:: Severity.ERROR
.. data:: Severity.WARNING
.. data:: Severity.NOTICE
.. data:: Severity.INFO
.. data:: Severity.DEBUG


Exceptions
------------------------------------------------

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

.. class:: TraceBufferAlreadyExistsError

   Raised when an trace buffer name is already in use.

.. class:: LogComponentRegisteredError

   Raised when an trace buffer name is already in use.