Difference between revisions of "Logging"

From MythTV Official Wiki
Jump to: navigation, search
(Suggest replacing logrotate with cron entries. May cause some welcome discussion.)
(And update DB logging)
(25 intermediate revisions by 4 users not shown)
Line 1: Line 1:
MythTV (starting with version 0.25) supports logging to various different loggers. Logging to the various loggers is enabled with command-line arguments. Additional information about application command-line arguments is available using the <code>--help</code> argument, for example:
+
Current MythTV supports logging to various loggers. Logging options are specified with command-line arguments.
 +
{{Note box|Starting with version 0.26, all log requests are handled by the [[Mythlogserver|mythlogserver]] application, which is automatically started as needed.  Logging arguments are still specified for mythbackend and mythfrontend applications and are passed to mythlogserver.  With 0.27, mythlogserver is now optional and it appears many distributions are disabling it (or users can do that with the command line option ''--nologserver''.)  In such cases, logs are written by each MythTV program according to the parameters below.}}
  
mythbackend --help
+
== General ==
  
or
+
All logging (regardless of specified logger) is affected by the arguments:
 +
 
 +
--loglevel                      Set the logging level.  All log messages at
 +
                                lower levels will be discarded.
 +
                                In descending order: emerg, alert, crit, err,
 +
                                warning, notice, info, debug
 +
                                defaults to info
 +
-v OR --verbose                Specify log filtering. Use '-v help' for level
 +
                                info.
  
mythfrontend --help
+
Typically, the default value for <code>--loglevel</code> and <code>--verbose</code> are appropriate for normal application execution. However, you may be asked to provide logs at a specific log level when helping debug issues.
  
 
Detailed help information is available for each argument by including the argument name after <code>--help</code>, for example:
 
Detailed help information is available for each argument by including the argument name after <code>--help</code>, for example:
Line 11: Line 20:
 
  mythbackend --help setloglevel
 
  mythbackend --help setloglevel
 
  mythbackend --help logpath
 
  mythbackend --help logpath
 
+
{{Note box|The legacy <code>--logfile</code> and <code>-l</code> arguments are no longer supported after 0.24.  Any script using --logfile or -l to start MythTV applications must be updated.}}
== General ==
+
 
+
All logging (regardless of specified logger) is affected by the arguments:
+
 
+
--setloglevel                  Change logging level of the existing master
+
                                backend.
+
--verbose OR -v                Specify log filtering. Use '-v help' for level
+
                                info.
+
 
+
Typically, the default value for <code>--setloglevel</code> and <code>--verbose</code> are appropriate for normal application execution. However, you may be asked to provide logs at a specific log level when helping debug issues.
+
  
 
== Loggers ==
 
== Loggers ==
Line 43: Line 42:
 
File logging is disabled by default and may be enabled with the argument:
 
File logging is disabled by default and may be enabled with the argument:
  
  --logfile OR --logpath OR -l    Writes logging messages to a file at logpath.
+
  --logpath                       Writes logging messages to a file in the directory logpath with
                                If a directory is given, a logfile will be
+
                                  filenames in the format: applicationName.date.pid.log.
                                created in that directory with a filename of
+
                                  This is typically used in combination with --daemon, and if used
                                applicationName.date.pid.log.
+
                                  in combination with --pidfile, this can be used with log
                                If a full filename is given, that file will be
+
                                  rotators, using the HUP call to inform MythTV to reload the file
                                used.
+
                                This is typically used in combination with
+
                                --daemon, and if used in combination with
+
                                --pidfile, this can be used with log rotators,
+
                                using the HUP call to inform MythTV to reload
+
                                the file (currently disabled).
+
  
When specifying a file path, file logging is only enabled for the application you are starting. All logging will be disabled for child processes started by that application (for example, preview generation, commercial detection, transcoding, and other jobs started by mythbackend). Therefore, you should always specify a directory as the argument for <code>--logpath</code> or <code>-l</code>.
+
{{Note box|File logging requires that the process writing the logs have permission on the specified logpath directory, as well as on the log files. This can be a challenge to configure properly in environments where different MythTV applications are run as different users.  Since mythlogserver is spawned (and re-spawned) by whichever application needs it, mythlogserver may be run as different users at different times--even during a single MythTV session.  Therefore, you may need to open up permissions or use <code>newgrp</code> to log in to a new group (a secondary group membership, such as mythtv) before starting the MythTV applications.  Alternatively, you can use [[#syslog_Logging|syslog logging]].}}
  
 
File logging output may be challenging to read in a terminal due to the amount of information included.  You may simplify the log file output with a log processor. For example, the command:
 
File logging output may be challenging to read in a terminal due to the amount of information included.  You may simplify the log file output with a log processor. For example, the command:
  
  perl -pwe 's#^(\d{4}(?:-\d{2}){2} \d{2}(?:\:\d{2}){2}\.\d{6} \w) \[\d+/\d+\] \S+ \S+ \(\S+\) - (.*$)#$1  $2#' /path/to/logfile
+
  perl -pwe '$| = 1; s#^(\d{4}(?:-\d{2}){2} \d{2}(?:\:\d{2}){2}\.\d{6} \w) \[\d+/\d+\] \S+ \S+ \(\S+\) - (.*$)#$1  $2#' /path/to/logfile
  
 
will scan the log file at <code>/path/to/logfile</code> and output (to <code>stdout</code>) a simplified log format equivalent to that used by console logging.  Change the <code>/path/to/logfile</code>, as appropriate for your system.
 
will scan the log file at <code>/path/to/logfile</code> and output (to <code>stdout</code>) a simplified log format equivalent to that used by console logging.  Change the <code>/path/to/logfile</code>, as appropriate for your system.
 +
 +
If you'd like to log full details while following the log file in a console with the above simplification, use the tail command:
 +
 +
tail -f /path/to/logfile | perl -pwe '$| = 1; s#^(\d{4}(?:-\d{2}){2} \d{2}(?:\:\d{2}){2}\.\d{6} \w) \[\d+/\d+\] \S+ \S+ \(\S+\) - (.*$)#$1  $2#'
  
 
=== syslog Logging ===
 
=== syslog Logging ===
Line 70: Line 67:
 
                                 Set to "none" to disable, defaults to none
 
                                 Set to "none" to disable, defaults to none
  
By default, logging to syslog is disabled. You should only enable syslog logging if you have also configured syslog on your host to handle the MythTV log messages appropriately.
+
By default, logging to syslog is disabled. You should only enable syslog logging if you have also [[:Category:Syslog Configuration Files|configured syslog]] on your host to handle the MythTV log messages appropriately.  Logging to syslog allows (via syslog configuration) user-specified log file names.
  
 
=== Database Logging ===
 
=== Database Logging ===
  
Database logging is enabled by default. It may be disabled with the argument:
+
Prior to 0.27, database logging is enabled by default. It may be disabled with the argument:
  
 
  --nodblog                      Disable database logging.
 
  --nodblog                      Disable database logging.
 +
 +
With 0.27+, database logging is off. It can be turned on with:
 +
 +
--enable-dblog
  
 
MythTV automatically cleans up the database logging information, to ensure your database does not grow out of control. All database logging information is removed within 2 weeks, so database logging is primarily useful for short-term log access, and should not be considered a valid long-term logging mechanism.
 
MythTV automatically cleans up the database logging information, to ensure your database does not grow out of control. All database logging information is removed within 2 weeks, so database logging is primarily useful for short-term log access, and should not be considered a valid long-term logging mechanism.
 +
 
== Log file cleanup ==
 
== Log file cleanup ==
  
When using <code>--logpath /path/to/log_directory</code>, one file for each run of a program and each of its children will be generated.
+
You may configure external applications, such as [https://fedorahosted.org/logrotate/ logrotate] or [http://www.gnu.org/software/rottlog/ GNU Rottlog], to rotate your log files. These programs allow you to specify exactly how to handle the multiple log files--including how often to rotate, how many old log files to keep and how long to keep them, where to place the log files, whether to compress them, and much more. Example configurations are available in the [[:Category:Log Rotation Configuration Files|Log Rotation Configuration Files category]].
As mentioned above, expect to see (for example) /var/log/mythtv/mythbackend.date.pid.log plus
+
 
similar entries for <code>mythcommflag, mythmetadatalookup</code> and <code>mythpreviewgen</code>.
+
Alternatively, a python script, [https://github.com/MythTV/packaging/blob/master/Gentoo/media-tv/mythtv/files/logcleanup.py logcleanup.py], is available to manage the multiple copies of these logs generated each time the applications restartWith its default settings, it will keep a minimum of five sets of logs for each application, and each set will be kept a minimum of seven days.  One log set is one file, along with any rotated, compressed copies generated by logrotate. This script can be set to run daily or weekly through cron.
Since this will create a lot of files in the logging directory, cleanup is '''strongly''' recommended.
+
 
Existing <code>logrotate</code> files might be removed and be replaced by cron entries.
+
[[Category:HOWTO]]
#!/bin/sh
+
# Sample /etc/cron/cron.hourly/mythtv file.
+
find /var/log/mythtv -type f -mtime +1 -name "mythpreviewgen.*.log" -delete
+
find /var/log/mythtv -type f -mtime +1 -name "mythcommflag.*.log" -delete
+
find /var/log/mythtv -type f -mtime +1 -name "mythmetadatalookup.*.log" -delete
+
find /var/log/mythtv -type f -mtime +6 -name "mythbackend.*.log" -delete
+
  find /var/log/mythtv -type f -mtime +4 -name "mythfrontend.*.log" -delete
+
The above will remove <code>mythpreviewgen, mythcommflag</code> and <code>mythmetadatalookup</code> log files that are one day old.
+
<code>mythbackend</code> log files get removed after 6 days etc.
+
Adjust as necessary for you system.
+

Revision as of 15:59, 15 November 2013

Current MythTV supports logging to various loggers. Logging options are specified with command-line arguments.

Important.png Note: Starting with version 0.26, all log requests are handled by the mythlogserver application, which is automatically started as needed. Logging arguments are still specified for mythbackend and mythfrontend applications and are passed to mythlogserver. With 0.27, mythlogserver is now optional and it appears many distributions are disabling it (or users can do that with the command line option --nologserver.) In such cases, logs are written by each MythTV program according to the parameters below.

General

All logging (regardless of specified logger) is affected by the arguments:

--loglevel                      Set the logging level.  All log messages at
                                lower levels will be discarded.
                                In descending order: emerg, alert, crit, err,
                                warning, notice, info, debug
                                defaults to info
-v OR --verbose                 Specify log filtering. Use '-v help' for level
                                info.

Typically, the default value for --loglevel and --verbose are appropriate for normal application execution. However, you may be asked to provide logs at a specific log level when helping debug issues.

Detailed help information is available for each argument by including the argument name after --help, for example:

mythbackend --help setloglevel
mythbackend --help logpath

Important.png Note: The legacy --logfile and -l arguments are no longer supported after 0.24. Any script using --logfile or -l to start MythTV applications must be updated.

Loggers

Console Logging

If running a MythTV application in a non-daemon mode, console logging will be enabled. Console logging is output to stdout.

Console logging is automatically disabled with the argument:

--daemon OR -d                  Fork application into background after startup.

(for MythTV daemon applications).

The console logging output contains a shortened format which better fits a standard terminal. Therefore, please provide full file logging output when attaching log files to bug tickets.

File Logging

The primary logger for MythTV applications is the file logger. File logging outputs detailed "debug" logging information about process execution, which can be very useful in debugging issues with MythTV. All log files uploaded to bug tickets should be those created from the file logger.

File logging is disabled by default and may be enabled with the argument:

--logpath                        Writes logging messages to a file in the directory logpath with
                                 filenames in the format: applicationName.date.pid.log.
                                 This is typically used in combination with --daemon, and if used
                                 in combination with --pidfile, this can be used with log
                                 rotators, using the HUP call to inform MythTV to reload the file


Important.png Note: File logging requires that the process writing the logs have permission on the specified logpath directory, as well as on the log files. This can be a challenge to configure properly in environments where different MythTV applications are run as different users. Since mythlogserver is spawned (and re-spawned) by whichever application needs it, mythlogserver may be run as different users at different times--even during a single MythTV session. Therefore, you may need to open up permissions or use newgrp to log in to a new group (a secondary group membership, such as mythtv) before starting the MythTV applications. Alternatively, you can use syslog logging.

File logging output may be challenging to read in a terminal due to the amount of information included. You may simplify the log file output with a log processor. For example, the command:

perl -pwe '$| = 1; s#^(\d{4}(?:-\d{2}){2} \d{2}(?:\:\d{2}){2}\.\d{6} \w) \[\d+/\d+\] \S+ \S+ \(\S+\) - (.*$)#$1  $2#' /path/to/logfile

will scan the log file at /path/to/logfile and output (to stdout) a simplified log format equivalent to that used by console logging. Change the /path/to/logfile, as appropriate for your system.

If you'd like to log full details while following the log file in a console with the above simplification, use the tail command:

tail -f /path/to/logfile | perl -pwe '$| = 1; s#^(\d{4}(?:-\d{2}){2} \d{2}(?:\:\d{2}){2}\.\d{6} \w) \[\d+/\d+\] \S+ \S+ \(\S+\) - (.*$)#$1  $2#'

syslog Logging

Logging to syslog may be enabled with the argument:

--syslog                        Set the syslog logging facility.
                                Set to "none" to disable, defaults to none

By default, logging to syslog is disabled. You should only enable syslog logging if you have also configured syslog on your host to handle the MythTV log messages appropriately. Logging to syslog allows (via syslog configuration) user-specified log file names.

Database Logging

Prior to 0.27, database logging is enabled by default. It may be disabled with the argument:

--nodblog                       Disable database logging.

With 0.27+, database logging is off. It can be turned on with:

--enable-dblog

MythTV automatically cleans up the database logging information, to ensure your database does not grow out of control. All database logging information is removed within 2 weeks, so database logging is primarily useful for short-term log access, and should not be considered a valid long-term logging mechanism.

Log file cleanup

You may configure external applications, such as logrotate or GNU Rottlog, to rotate your log files. These programs allow you to specify exactly how to handle the multiple log files--including how often to rotate, how many old log files to keep and how long to keep them, where to place the log files, whether to compress them, and much more. Example configurations are available in the Log Rotation Configuration Files category.

Alternatively, a python script, logcleanup.py, is available to manage the multiple copies of these logs generated each time the applications restart. With its default settings, it will keep a minimum of five sets of logs for each application, and each set will be kept a minimum of seven days. One log set is one file, along with any rotated, compressed copies generated by logrotate. This script can be set to run daily or weekly through cron.