<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2003/XInclude" type="topic" id="logging" xml:lang="es">

  <info>

    <link type="guide" xref="index#specific-how-tos"/>

    <credit type="author copyright">

      <name>Philip Withnall</name>

      <email its:translate="no">philip.withnall@collabora.co.uk</email>

      <years>2015</years>

    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>

      Logging debug and information output from libraries and programs

    </desc>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Daniel Mustieles</mal:name>

      <mal:email>daniel.mustieles@gmail.com</mal:email>

      <mal:years>2016</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Javier Mazorra</mal:name>

      <mal:email>mazi.debian@gmail.com</mal:email>

      <mal:years>2016</mal:years>

    </mal:credit>

  </info>

  <title>Registro</title>

  <synopsis>

    <title>Resumen</title>

      Logging debug and informational output from libraries and programs is an

      open problem, and there are various methods for converting multiple

      streams of log output into the customary stdout and stderr streams. Below

      are some suggestions for how to implement logging. However, the most

      important thing is to ensure that logging is consistent, so that log data

      can be accessed and searched with a minimum of effort, since that’s what

      it’s used for. Using different logging mechanisms and formats in different

      projects is not the right approach.

    <list>

      <item>

        Use the GLib logging framework instead of logging directly to stderr and

        stdout. (<link xref="#glib-logging-framework"/>)

      
</item>

      <item>

        If systemd can be a dependency of the project, consider logging directly

        to the journal. (<link xref="#journald-integration"/>)

      
</item>

      <item>

        Do not implement log rotation and deletion; leave that to system

        services. (<link xref="#log-rotation"/>)

      
</item>

    </list>

  </synopsis>

  <section id="glib-logging-framework">

    <title>Entorno de trabajo de registro de GLib</title>

      GLib provides

      <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html">a

      logging framework</link> based around the

      <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-log">g_log()</link>

      function, with convenience wrappers

      <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-debug">g_debug()</link>,

      <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-message">g_message()</link>,

      <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-warning">g_warning()</link>

      and

      <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-error">g_error()</link>.

      The GLib logging framework has a few useful features:

    <list>

      <item>

        Programmatic redirection of log messages using

        <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-log-set-handler">g_log_set_handler()</link>.

      
</item>

      <item>

        Multiple logging domains, which can be processed separately.

      
</item>

      <item>

        Multiple log levels, which can be processed separately. For example,

        this allows debug messages to be turned on and off at runtime.

      
</item>

      <item>

        Support for automatically aborting a program on ‘fatal’ messages.

      
</item>

    </list>

      These should be used in preference to functions like

      printf(),

      <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-print">g_print()</link>

      and

      <link href="https://developer.gnome.org/glib/stable/glib-Warnings-and-Assertions.html#g-printerr">g_printerr()</link>,

      due to their enhanced flexibility. The logging functions allow log

      processing to be done in code, rather than by external shell scripting,

      which simplifies everything.

      A key reason to use the logging framework is that it is used in GLib and

      other related libraries already; by using it, all log messages are then

      going through the same system and can be processed similarly.

      To use the GLib logging framework, define

      <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#G-LOG-DOMAIN:CAPS">G_LOG_DOMAIN</link>

      for the project so it’s unique from all other projects. Call

      g_debug("Message") to log a debug message.

      If the default GLib log handlers are not sufficient, for example if log

      messages need to be in a custom format or

      <link xref="#journald-integration">journald integration</link> is needed,

      set up a log handler with the following code:

static const gchar *

log_level_to_string (GLogLevelFlags level)

{

  switch (level)

    {

      case G_LOG_LEVEL_ERROR: return "ERROR";

      case G_LOG_LEVEL_CRITICAL: return "CRITICAL";

      case G_LOG_LEVEL_WARNING: return "WARNING";

      case G_LOG_LEVEL_MESSAGE: return "MESSAGE";

      case G_LOG_LEVEL_INFO: return "INFO";

      case G_LOG_LEVEL_DEBUG: return "DEBUG";

      default: return "UNKNOWN";

    }

}

static void

log_handler_cb (const gchar    *log_domain,

                GLogLevelFlags  log_level,

                const gchar    *message,

                gpointer        user_data)

{

  const gchar *log_level_str;

  /* Ignore debug messages if disabled. */

  if (!debug_enabled && (log_level & G_LOG_LEVEL_DEBUG))

    {

      return;

    }

  log_level_str = log_level_to_string (log_level & G_LOG_LEVEL_MASK);

  /* Use g_printerr() for warnings and g_print() otherwise. */

  if (flags <= G_LOG_LEVEL_WARNING)

    {

      g_printerr ("%s: %s: %s\n", log_domain, log_level_str, message);

    }

  else

    {

      g_print ("%s: %s: %s\n", log_domain, log_level_str, message);

    }

}

g_log_set_handler ("log-domain",

                   G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION,

                   log_handler_cb, NULL);

    <section id="exceptions">

      <title>Excepciones</title>

      <list>

        <item>

          Do not use g_message() in normal code to print output.

          Printing output should be done at the top level of an application,

          using g_print(), and should be quite rare; i.e. only done

          in command line applications.

        
</item>

        <item>

          Do not use  g_warning() in library code. Use

          <link xref="gerror">GErrors</link> instead.

        
</item>

        <item>

          Similarly, do not set up log handlers in library code. Log messages

          should propagate through library code and be handled in a log handler

          at the top level of an application.

        
</item>

      </list>

    </section>

  </section>

  <section id="journald-integration">

    <title>Integración con journald</title>

      Compared to conventional syslog-style logs, journald supports storage of

      structured logging data, which can make post-hoc analysis of logs much

      easier. If it’s possible to add systemd-journal as a

      dependency to a project, the project’s log handling function could be

      extended to use

      <link href="http://0pointer.de/public/systemd-man/sd_journal_send.html">sd_journal_print()

      and sd_journal_send()</link> instead of

      g_print() and g_printerr().

      For more information, see this

      <link href="http://0pointer.de/blog/projects/journal-submit.html">article

      on logging to the journal</link>.

  </section>

  <section id="log-rotation">

    <title>Rotación de registros</title>

      Log file rotation is one feature which is out of scope of the GLib logging

      system. It should be handled by the normal system logging mechanisms, such

      as <cmd>logrotate</cmd> or <cmd>systemd-journald</cmd>.

  </section>

</page>