ldapsaisie/doc/conf/LSlog.docbook

<?xml version="1.0" encoding="UTF-8" ?>
<sect3 id="config-LSlog">
  <title>Configuration de la journalisation</title>

<para>Cette section décrit le tableau de configuration de la journalisation
de l'application.</para>

<programlisting linenumbering="unnumbered">
<citetitle>Structure</citetitle>...
<![CDATA[$GLOBALS['LSlog'] = array(
  'enable' => [booléen],
  'level' => '[niveau]',
  'handlers' => array(
    '[handler 1]',
    array (
      'handler' => [handler 2],
      'enabled' => [booléen],
      'level' => '[niveau]',
      'loggers' => array('logger1', [...]),
      'excluded_loggers' => array('logger2', [...]),
      'format' => '[LSformat]',
      'cli_format' => '[LSformat]',
      'datetime_prefix' => [booléen],
      'datetime_format' => '[format date()]',
      // Autres paramètres propre à ce handler
      [...]
    ),
    [...]
  ),
  'loggers' => array (
    'logger1' => array (
      'level' => 'DEBUG',
    ),
    'logger2' => array (
      'enabled' => false,
    ),
    [...]
  );
);]]>
...
</programlisting>

<!-- Début Paramètres Configuration -->
<variablelist>
<title>Paramètres de configuration</title>

<varlistentry>
  <term>enable</term>
  <listitem>
    <simpara>Booléen permatant d'activer ou désactiver complètement la
    journalisation. Par défaut : <literal>False</literal></simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>level</term>
  <listitem>
    <simpara>Ce paramètre défini le niveau minimum de la journalisation :
    tous les messages des niveaux inférieurs ne seront pas inclus dans le
    journal de l'application. Les niveaux de journalisation gérés par
    l'application sont (dans l'ordre du plus petit au plus grand) :</simpara>
    <itemizedlist>
      <listitem><simpara>TRACE</simpara></listitem>
      <listitem><simpara>DEBUG</simpara></listitem>
      <listitem><simpara>INFO</simpara></listitem>
      <listitem><simpara>WARNING</simpara></listitem>
      <listitem><simpara>ERROR</simpara></listitem>
      <listitem><simpara>FATAL</simpara></listitem>
    </itemizedlist>
  </listitem>
</varlistentry>

<varlistentry>
  <term>handlers</term>
  <listitem>
    <para>Tableau permettant de configurer les <emphasis>handlers</emphasis> de la
    journalisation. Chaque <emphasis>handler</emphasis> gère les messages
    journalisés d'une manière qui lui est propre.</para>

    <para>Plusieurs <emphasis>handlers</emphasis> peuvent être configurés en même
    temps (y compris plusieurs <emphasis>handlers</emphasis> du même type).</para>

    <para>Ce tableau peut contenir simplement le nom du type de <emphasis>handler
    </emphasis>à utiliser ou bien des tableaux configurant un à un chacun des
    <emphasis>handlers</emphasis>. Dans ce second cas, la structure de la
    configuration d'un <emphasis>handler</emphasis> est la suivante :</para>

<programlisting linenumbering="unnumbered">
<citetitle>Structure</citetitle>...
<![CDATA[array(
  'handler' => [type],
  'level' => '[niveau]',
  'loggers' => array('logger1', [...]),
  'excluded_loggers' => array('logger2', [...]),
  'format' => '[LSformat]',
  'cli_format' => '[LSformat]',
  'datetime_prefix' => [booléen],
  'datetime_format' => '[format date()]',
  // Autres paramètres propre à ce handler
  [...]
)]]>
...
</programlisting>

    <variablelist>
      <title>Paramètres de configuration d'un handler</title>

<varlistentry>
  <term>handler</term>
  <listitem>
    <simpara>Type du <emphasis>handler</emphasis> (voir ci-dessous).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>level</term>
  <listitem>
    <simpara>Ce paramètre défini le niveau minimum de la journalisation
    spécifique à cet <emphasis>handler</emphasis>. Si ce paramètre est omis,
    le niveau global sera utilisé. Les valeurs possibles de ce paramètre
    sont les mêmes que pour le paramètre <literal>$GLOBALS['LSlog']['level']
    </literal>.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>enabled</term>
  <listitem>
    <simpara>Booléen permettant d'activer ou désactiver cet <emphasis>handler</emphasis>
    (paramètre facultatif, par défaut : <literal>True</literal>).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>loggers</term>
  <listitem>
    <simpara>Liste exhautive des composants dont les messages doivent être traités
    par ce handler (paramètre facultatif, par défaut : tous les composants).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>excluded_loggers</term>
  <listitem>
    <simpara>Liste exhautive des composants dont les messages ne doivent pas être
    traités par ce handler (paramètre facultatif, par défaut : aucun composant).
    </simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>format</term>
  <listitem>
    <para>&LSformat; des messages de cet journalisé par ce handler. Ce format
    est composé à partir des informations décritent ci-dessous. Par défaut :
    <literal>%{requesturi} - %{remoteaddr} - %{ldapservername} - %{authuser} - %{logger} - %{level} - %{message}</literal>
    </para>

    <variablelist>

<varlistentry>
  <term>level</term>
  <listitem>
    <simpara>Le niveau du message.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>message</term>
  <listitem>
    <simpara>Le message.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>logger</term>
  <listitem>
    <simpara>Le composant ayant déchenché cette journalisation.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>clibinpath</term>
  <listitem>
    <simpara>Le nom du script ayant déclenché cette jounalisation (uniquement en cas d'exécution en ligne de commande).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>requesturi</term>
  <listitem>
    <simpara>L'URL de la page courante (uniquement dans un contexte Web).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>remoteaddr</term>
  <listitem>
    <simpara>L'adresse IP du client (uniquement dans un contexte Web).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>ldapservername</term>
  <listitem>
    <simpara>Le nom du serveur LDAP courant.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>authuser</term>
  <listitem>
    <simpara>Le DN de l'utilisateur connecté (uniquement dans un contexte Web).</simpara>
  </listitem>
</varlistentry>

    </variablelist>
  </listitem>
</varlistentry>

<varlistentry>
  <term>cli_format</term>
  <listitem>
    <simpara>&LSformat; des messages de cet journalisé par ce handler dans le
    cas d'une exécution en ligne de commande. Ce format est composé à partir des
    même informations que le paramètre <literal>format</literal> (voir ci-dessus).
    Par défaut : <literal>%{clibinpath} - %{logger} - %{level} - %{message}</literal>
    </simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>datetime_format</term>
  <listitem>
    <simpara>Booléen permettant de définir si le message doit être préfixé de la
    date et heure courante. La valeur par défaut dépends de l'handler (en règle
    général, toujours actif sauf lorsque le canal de journalisation l'ajoute déjà).
    </simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>datetime_format</term>
  <listitem>
    <simpara>Format de la date et heure lorsque celle-ci est ajoutée en préfixe
    du message (voir paramètre <literal>datetime_format</literal>). Le format
    correspond à celui attendu par la function <literal>date()</literal> de &php;
    . Consultez la <ulink url='http://php.net/date'>documentation officielle
    </ulink> pour plus de détails (Par défaut : <literal>Y/m/d H:i:s</literal>).
    </simpara>
  </listitem>
</varlistentry>

    </variablelist>

    <para>Il existe plusieurs types d'<emphasis>handlers</emphasis> gérés par
    l'application :</para>
    <variablelist>
      <varlistentry>
        <term>file</term>
        <listitem>
          <simpara>Journalisation dans un simple fichier texte. Le chemin du
          fichier peut être configuré via le paramètre <literal>path</literal>.
          Si ce paramètre est omis, le chemin du fichier par défaut est soit la
          valeur de la variable <literal>$GLOBALS['LSlog']['filename']</literal>
          (pour la rétro-compatibilité avec les anciennes versions d'LdapSaisie)
          ou à défaut : <literal>tmp/LS.log</literal>.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>syslog</term>
        <listitem>
          <simpara>Journalisation via le service <emphasis>syslog</emphasis>.
          Il est possible de configurer une priorité systématique pour les
          messages journalisés. À défaut, la priorité sera déterminée
          automatiquement en fonction du niveau du message. Les valeurs
          possibles de ce paramètre sont : <literal>EMERG, ALERT, CRITICAL,
          ERROR, WARNING, NOTICE, INFO, DEBUG</literal></simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>system</term>
        <listitem>
          <simpara>Journalisation via le gestionnaire d'erreurs PHP. Cet <emphasis>
          handler</emphasis> utilise la fonction PHP <literal>error_log</literal>.
          Pour plus d'informations sur comment configurer le gestionnaire d'erreurs
          PHP, consulter la <ulink url='https://www.php.net/error_log'>documentation
          officielle</ulink>.</simpara>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>email</term>
        <listitem>
          <simpara>Journalisation via l'envoi d'un email : chaque message journalisé
          déclenchera l'envoi d'un email au destinataire configuré. L'adresse email
          du destinataire peut-être configurée via le paramètre <literal>recipient
          </literal>.</simpara>
          <note><para>Il est conseillé d'utiliser ce type d'<emphasis>handler</emphasis>
          avec un niveau minimum de journalisation important (<literal>FATAL</literal>
          recommandé) pour ne pas déclencher un nombre trop important d'envois d'emails.
          </para></note>
        </listitem>
      </varlistentry>

    </variablelist>
  </listitem>
</varlistentry>

<varlistentry>
  <term>loggers</term>
  <listitem>
    <para>Tableau permettant de configurer la journalisation composant par composant.
    Chaque composant peut avoir son propre <literal>logger</literal> ce qui permet
    alors, par exemple, de configurer le niveau de log spécifiquement pour ce
    composant.</para>

    <para>Le nom des composant correspond en général au nom de la classe &php;
    correspondante, ou bien encore le nom d'une commande (lors d'une exécution en
    ligne de commande).</para>

    <note><para> Par défaut, le nom du composant ayant déclenché un message
    journalisé est affiché juste avant le niveau de log.</para></note>

    <variablelist>
      <title>Paramètres de configuration d'un logger</title>

<varlistentry>
  <term>enabled</term>
  <listitem>
    <simpara>Booléen permettant de désactiver complètement les logs du composant
    (par défaut: <literal>True</literal>).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>level</term>
  <listitem>
    <simpara>Niveau de log spécifique pour ce composant (par défaut: le niveau
    de log global).</simpara>
  </listitem>
</varlistentry>

    </variablelist>
  </listitem>
</varlistentry>

</variablelist>
<!-- Fim Paramètres Configuration -->

</sect3>