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
• deprecated-calls.log (since iTop 3.0.0) : calls to deprecated PHP methods or files
• tools.log : tools errors, currently used only in backup

In addition to the files, in case of uncatched Exceptions, iTop can write logs into the EventIssue class. You can access them using this query: SELECT EventIssue in the “Run Queries” menu.

All exceptions are not written (for instance, REST services exceptions are not). Globally, they are written if those conditions are met:

• The issue occur in a standard page (under UI.php)
• The issue occur in a portal page, and an adequate level of log_level_min.write_in_db is present (see filter_portal_exceptions below)

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>

Automatic log purge:
You can activate the purge using the log_purge.enabled parameter (disabled by default).
You can define the log lifetime using the log_purge.max_keep_days parameter (365 day by default).

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) :

abstract class LogAPI {
        public const LEVEL_ERROR   = 'Error';
        public const LEVEL_WARNING = 'Warning';
        public const LEVEL_INFO    = 'Info';
        public const LEVEL_OK      = 'Ok';
        public const LEVEL_DEBUG   = 'Debug';
        public const LEVEL_TRACE   = 'Trace';

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 like the examples below.
Note that since 2.7.5 and 3.0.0, iTop core channels are regrouped in the LogChannels class.

  'log_level_min' => LogAPI::LEVEL_TRACE,

To set specific levels per channels :

  'log_level_min' => array(
                LogChannels::INLINE_IMAGE => LogAPI::LEVEL_TRACE,
                'UserRequest'             => LogAPI::LEVEL_TRACE,
                'MyCustomExtension'       => LogAPI::LEVEL_INFO,
        ),

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

  'log_level_min' => array(
                ''                        => LogAPI::LEVEL_WARNING,
                LogChannels::INLINE_IMAGE => LogAPI::LEVEL_TRACE,
                'UserRequest'             => LogAPI::LEVEL_TRACE,
                'MyCustomExtension'       => LogAPI::LEVEL_INFO,
        ),

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

Since iTop 3.0, exceptions can be logged using \ExceptionLog::LogException($oException);.

You can configure its behavior as usually with log_level_min and log_level_min.write_in_db.
The channel must be the class of the exception, if not found it will try all the parent tree until Exception.

When no configuration exists, beware DB logging is enabled for the level Error.

The portal trigger “Warning” exceptions, logs are not written in db by default.

For example, to enable some of them, you can configure:

  'log_level_min.write_in_db' => array(
                'CoreCannotSaveObjectException' => LogAPI::LEVEL_WARNING,
                'CoreOqlException' => LogAPI::LEVEL_WARNING,
        ),

Since this behaviour is generic, extension developers can use it by calling \ExceptionLog::LogException($oException);.

In this case, they are invited to throw specific Exception in order to be able to filter them by class.

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.