
.. _logging-page:

#######
Logging			
#######

|ProductName| provides a logging system used both for the internal logging and also available
for logging errors, warnings, info and debug in your own application.

.. image:: ../../images/log_notepad.png
    :width: 45%
.. image:: ../../images/log_console.png
    :width: 45%


The logged messages can either be saved to a file (:class:`LogDestinationFile <cee::LogDestinationFile>`) or written 
directly to a console (:class:`LogDestinationConsole <cee::LogDestinationConsole>`). You can also create your own
log destination by deriving from :class:`LogDestination <cee::LogDestination>` and overriding the 
:func:`log() <cee::LogDestination::log>` method. This is useful if you already have a logging system in your application
and would like to incorporate the logging message from Envision toolkits into your application log.

The :class:`LogManager <cee::LogManager>` controls the logging. You can get the LogManager with the 
:func:`CoreComponent::logManager() <cee::CoreComponent::logManager>` method.
Set the destination (file or console) using :func:`LogManager::setDestination() <cee::LogManager::setDestination>`.

The log manager provides 4 levels of log messages:

-   Errors (Level 1): :func:`LogManager::logError <cee::LogManager::logError>`
-   Warnings (Level 2): :func:`LogManager::logWarning <cee::LogManager::logWarning>`
-   Info (Level 3): :func:`LogManager::logInfo <cee::LogManager::logInfo>`
-   Debug (Level 4): :func:`LogManager::logDebug <cee::LogManager::logDebug>`

Each of these take a logger name and the log message. Log an error message like this:


.. code-block:: cpp
    
    m_instance.logManager()->logError("myComp.import", "Could not open file");

The logger names are structured in a hierarchical system with parent/child categories which simplifies 
the logger level control. 
You can have different user defined logger names for your different modules or areas, for instance:

-    `Comp.import`
-    `Comp.export`
-    `Comp.visual`

The loggers used by Envision toolkits are all under the "cee." logger. The logger for each component is called 
"cee.comp.{COMPONENT_NAME}", e.g. cee.comp.UnstructGrid. The logger "cee.cvf.*" is used for the internal 
Envision rendering engine.

You specify the log levels to use for your application with :func:`cee::LogManager::setLevel` 
with a logger name and a level (1-4). 
This log level will apply to the specified logger name and all its children. Consider the following code:

.. code-block:: cpp

    m_instance.logManager()->setLevel("", 2);                // Only warnings and errors as a general rule
    m_instance.logManager()->setLevel("myComp", 3);          // Also show info from your app (myComp.*) destinations
    m_instance.logManager()->setLevel("myComp.import", 4);   // Also show debug from import (myComp.import.*) destinations

This will log errors and warnings globally, but also show info messages from everything under `myComp.*`.
Debug messages from `myComp.import` will in addition be logged, but `myComp.export` will still be at level
3 and just show errors, warnings and info.

Good practice is setting up the logger at the same place as you initialize |ProductName|. Once the logger is set up,
you can send log messages from anywhere using `m_instance.logManager()->log*("logger name", "logger message")`.

Logger example setup from the demo application:

.. code-block:: cpp

    QString logFile = logDir.absoluteFilePath("HOOPSEnvisionQtDemoLog.txt");
    compInst->logManager()->setDestination(new cee::LogDestinationFile(cee::qt::Utils::toStr(logFile)));
    compInst->logManager()->setLevel(cee::Str(""), 2);          // Only warnings and errors as a general rule
    compInst->logManager()->setLevel(cee::Str("cee.comp"), 3);  // Also show info from components (cee.comp.*) destinations
    compInst->logManager()->setLevel(cee::Str("cee.demo"), 3);  // Also show info from app (cee.demo.*) destinations

    compInst->addVersionToLog();

    QTime time = QTime::currentTime();
    QDate date = QDate::currentDate();
    QString timeString = "Log for HOOPS Envision Qt Demo App. Started: " + date.toString() + " " + time.toString();
    compInst->logManager()->logInfo("cee.demo", cee::qt::Utils::toStr(timeString));

