iTop logs

As lots of other applications, iTop writes a lot of useful informations in log files. They all can be found in the log directory just below iTop root.

Beware that this directory shouldn't be readable by web users : see Secure critical directories access.

• setup.log
• install-<date>.xml : summary of choices made in the installation wizard
• setup-queries-<date>_<time>.sql : list of queries sent to the DB during the “Updating database schema” step

• error.log
• deadlocks.log (since iTop 2.7.1) : additional trace info for DB deadlocks
• tools.log : tools errors, currently used only in backup

Since iTop 2.7.0, log files are rotated monthly. This means previous month log is suffixed with <year>-month<month_no>.
For example if we're in february 2021 current error log will be error.log, and previous month (so january 2021) error log will be error.2021-month01.log.

The rotation period can be configured in iTop config using the log_filename_builder_impl parameter.
Possible values :

• DefaultLogFileNameBuilder : no rotation
• DailyRotatingLogFileNameBuilder : suffix <year>-<month_no>_<day_no>
• WeeklyRotatingLogFileNameBuilder : suffix <year>-week<week_no>
• MonthlyRotatingLogFileNameBuilder : suffix <year>-month<month_no>

Since iTop 2.7.0, the log_level_min config parameter allows to filter the logs. This allows to specify which log level to keep per channel.

Levels are inclusive all the way up this hierarchy (values correspond to LogAPI class constants) :

• LogAPI::LEVEL_TRACE
• LogAPI::LEVEL_DEBUG
• LogAPI::LEVEL_OK
• LogAPI::LEVEL_INFO
• LogAPI::LEVEL_WARNING
• LogAPI::LEVEL_ERROR

So for example filtering on LEVEL_INFO will include logs of levels : LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR.

To apply a level to all channels, simply set the following parameter value in the iTop configuration file :

  'log_level_min' => LogAPI::LEVEL_TRACE,

To set specific levels per channels :

  'log_level_min' => array(
                'InlineImage' => LogAPI::LEVEL_TRACE,
                'UserRequest' => LogAPI::LEVEL_TRACE,
        ),

As the default log channel (\LogAPI::CHANNEL_DEFAULT) is “” (empty string), you can also do :

  'log_level_min' => array(
                ''            => LogAPI::LEVEL_WARNING,
                'InlineImage' => LogAPI::LEVEL_TRACE,
                'UserRequest' => LogAPI::LEVEL_TRACE,
        ),

Existing channels are detailed in a dedicated wiki page : iTop logs channels

Simplest answer : use the IssueLog class and its static logging methods : Trace, Ok, Info, Warning, Error.

If using a specific channel, you should say it in your module's documentation !

If you want to log to a specific file and/or customize behavior, you could create your own log implementation ! Extending LogAPI abstract class would help. If so, don't forget to :

• Call the Enable method ! Also, you could overwrite it to log to a specific file path (see for example \DeadLockLog::Enable)
• Set the proper LEVEL_DEFAULT const value for your implementation, to one of the LEVEL_* const
• Document ! ;)

You can also add a new rotation behavior by implementing the iLogFileNameBuilder interface or the RotatingLogFileNameBuilder abstract class.