.. _ecflow_log_file:

ecFlow log file
///////////////


If this file exists at the beginning of ecFlow execution, it is appended
to. Otherwise, it is created. The location and name of the log file can
be configured using the environment variable
`ECF_LOG <https://confluence.ecmwf.int/display/ECFLOW/ECFLOW+Server+environment+variables>`__,
which can be set before the ecFlow server starts.

+------+---------------------------------------------------------------+
|      | Meaning                                                       |
|Symbol|                                                               |
|      |                                                               |
+======+===============================================================+
| MSG  | Information message generated by ecflow_client commands in a  |
|      | job or user action, normal operation.                         |
+------+---------------------------------------------------------------+
| LOG  | Information message generated by task or ECF, normal          |
|      | operation. These are mostly messages generated when nodes go  |
|      | through status changes.                                       |
+------+---------------------------------------------------------------+
| ERR  | An error message, abnormal operation the action could not be  |
|      | done. Some errors are ignored on the client-side, for example |
|      | trying to send a label or an event that does not exist in     |
|      | ecFlow server is an error on the server side but not on the   |
|      | client-side.                                                  |
+------+---------------------------------------------------------------+
| WAR  | Warning message, not an error but corrective action was       |
|      | taken. For example, using an old version of the client may    |
|      | cause a warning message to be printed.                        |
+------+---------------------------------------------------------------+
| DBG  | Debugging message, by default these are not visible they must |
|      | be turned on by a privileged user.                            |
+------+---------------------------------------------------------------+
|others| There could be a keyboard echo in the log file if ecFlow is   |
|      | running interactively; these lines should be ignored by       |
|      | programs processing the log file.                             |
+------+---------------------------------------------------------------+

The log file contains all the actions of the ecFlow server and shows
information such as the halt, shutdown, etc. It is a pure text file and
can easily be processed by other programs. For example, ecflow_ui uses
this file to show the **timeline** window.

The syntax of the log file is fairly simple. For each action in ecFlow,
a line is output. The format is as follows::

  XXX:[HH:MM:SS D.M.YYYY] command:fullname [+additional information]

Where *XXX* is one of the symbols in the above table. The
**timestamp** inside [] is the system time, not the suite time, which
may differ.

.. note:: 
  
  User commands often generate both **MSG** and **LOG**
  level messages. **MSG** is the command executed and **LOG** is the
  effect it had on the node or nodes.

.. note:: 

  The log file is not removed so it needs to be managed. We
  tend to compress and archive our log files each day using an ecFlow
  controlled script.

The log file grows over time and **should** be managed. You can
manipulate the log files using the client command --log. Type::

  ecflow_client --help log
  
for details. This allows you to get, clear, flush, or create a new log file.
