.. _file-logger:

********************
File Logger
********************

.. index:: File Logger, logging; file

Overview
====================

The FileLogger writes samples to a file stored on a persistent 
storage device, such as the flash file system.

.. warning:: The ConnectPort products on which Dia is written to run
    have limitations on the number of files which may be held open
    simultaneously.  Multiple files also impede performance.  It is
    recommended that a single logger be used.  If necessary, the file can
    be post-processed and filtered to extract information.  The resulting
    log files are platform independent and may be copied to a host PC for
    analysis. If this is not possible, keep the overall file count low.


Configuration
====================

A typical FileLogger configuration block looks like this::

    - name: file_logger
      driver: channels.logging.file_logger.file_logger:FileLogger
      settings:
          filename: WEB/python/dia.log
          event_volume_size_k: 512
          include_channel_prefixes:
           - template
           - sensor0
          exclude_channel_prefixes:
           - sensor0.temperature
           - noisy_device.channel
          sample_index_frequency: 128

Settings
--------------------

Log Creation
~~~~~~~~~~~~~~~~~~~~
filename (required)
    Absolute path to the file that will be created and/or read.

event_volume_size_k (required)
    Size in kilobytes of the event portion of the log.  The resulting
    file will be larger than the size specified in order to store
    additional information about the system.

Operating Parameters
~~~~~~~~~~~~~~~~~~~~

sample_index_frequency (optional)
    The log will store an index of the total state of the system after
    the configured number of events.  Lower numbers will speed up
    random access to events in the log at the cost of decreasing the
    number of events that the log can store.

include_channel_prefixes (optional)
    If specified, this parameter will determine the list of prefixes
    to channels that will be stored in this log.  

exclude_channel_prefixes (optional)
    If specified, this parameter will determine the list of prefixes
    to channels that willnot be stored in this log.  If both 
    ``include_channel_prefixes``and ``exclude_channel_prefixes``
    are specified, the include list is calculated first, and then
    prefixes from the exclude list are removed from the result.
