path: root/doc/book-enea-edge-getting-started/doc/log_collector.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="log_collector">
  <title>Using the Log Collector</title>

  <para>Troubleshooting problems on a uCPE device require an analysis of a set
  of data and information i.e. logs collected from the uCPE device and/or the
  Enea Edge Management application. The following information describes how
  the log collection mechanism works.</para>

  <section id="log_collect_ucpem">
    <title>Log collecting using the Enea Edge Management application</title>

    <para>The Enea Edge Management application allows for collecting a set of
    logs and state information from a uCPE device.</para>

    <section id="log_collect">
      <title>Collecting the Logs</title>

      <para>Collect the necessary log files and system details, then create an
      archive (a tar file) on the uCPE device in the
      <filename>/var/odm/log/archives</filename> folder:</para>

      <orderedlist>
        <listitem>
          <para>Access <emphasis role="bold">Operations</emphasis> and then
          select <emphasis role="bold">Collect Debug Logs</emphasis>.</para>
        </listitem>

        <listitem>
          <para>Provide a file name in the new window.</para>
        </listitem>

        <listitem>
          <para>Press the <emphasis role="bold">Execute</emphasis>
          button.</para>

          <para>A success message is shown in the same window as shown below.
          At this moment, the process of collecting logs on the uCPE device
          starts.</para>
        </listitem>

        <figure>
          <title>Collecting Debug Logs</title>

          <mediaobject>
            <imageobject>
              <imagedata align="center" contentwidth="500"
                         fileref="images/collect_debug_logs.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </orderedlist>

      <note>
        <para>It might take some time for the archive to be created. When the
        operation completes, a "CollectLogsComplete" notification is sent from
        the uCPE device to the Enea Edge Management application. This can be
        viewed in the GUI in the <emphasis role="bold">Faults</emphasis> menu,
        after selecting <emphasis role="bold">Events</emphasis>.</para>

        <figure>
          <title>Collecting Debug Logs</title>

          <mediaobject>
            <imageobject>
              <imagedata align="center" contentwidth="500"
                         fileref="images/fault_events.png" />
            </imageobject>
          </mediaobject>
        </figure>
      </note>
    </section>

    <section id="view_logs">
      <title>View collected Logs</title>

      <para>A list with the archives containing already collected logs will be
      shown in the <emphasis role="bold">Device File Listing</emphasis>
      table:</para>

      <orderedlist>
        <listitem>
          <para>Access the <emphasis role="bold">Files</emphasis> menu and
          select the <emphasis role="bold">Download</emphasis> button.</para>
        </listitem>

        <listitem>
          <para>Press the <emphasis role="bold">List</emphasis> button.</para>

          <figure>
            <title>Device File Listing Table</title>

            <mediaobject>
              <imageobject>
                <imagedata align="center" contentwidth="500"
                           fileref="images/archive_list.png" />
              </imageobject>
            </mediaobject>
          </figure>
        </listitem>
      </orderedlist>

      <note>
        <para>If the filename you specified does not appear, it might still be
        in the process of creation. Click on the <emphasis
        role="bold">Refresh</emphasis> icon at the bottom of the table until
        you can see the desired file listing.</para>
      </note>
    </section>

    <section id="download_fr_dev">
      <title>Downloading Logs from the uCPE Device</title>

      <para>This option transfers a debug file archive from the uCPE device to
      Enea Edge Management application.</para>

      <orderedlist>
        <listitem>
          <para>Access the <emphasis role="bold">Files</emphasis> menu and
          select the <emphasis role="bold">Download</emphasis> button.</para>
        </listitem>

        <listitem>
          <para>Press the <emphasis role="bold">List</emphasis> button.</para>
        </listitem>

        <listitem>
          <para>In the <emphasis role="bold">Device File Listing</emphasis>
          table, select the archive you want to download from the uCPE device
          to Enea Edge Management.</para>
        </listitem>

        <listitem>
          <para>Press the <emphasis role="bold">Download from
          Device</emphasis> button.</para>

          <para>The archive will be downloaded from the uCPE device and stored
          on the Enea Edge Management application.</para>
        </listitem>
      </orderedlist>

      <note>
        <para>The archive will not be deleted from the uCPE device after
        download.</para>
      </note>
    </section>

    <section id="download_logs_locally">
      <title>Downloading collected Logs locally</title>

      <para>This option downloads a logs archive from the Enea Edge Management
      application to a local (user) machine for analysis. The archive must
      first be available in the Enea Edge Management application in order to
      be downloaded.</para>

      <orderedlist>
        <listitem>
          <para>Access the <emphasis role="bold">Devices</emphasis> menu and
          select <emphasis role="bold">Files</emphasis>.</para>
        </listitem>

        <listitem>
          <para>Select the <emphasis role="bold">Downloaded Files</emphasis>
          tab.</para>
        </listitem>

        <listitem>
          <para>Select an archive from the <emphasis role="bold">Downloaded
          Files</emphasis> table.</para>
        </listitem>

        <listitem>
          <para>Click the <emphasis role="bold">Download</emphasis>
          button.</para>

          <para>The file will be downloaded in the download folder of the
          supported browser in use.</para>

          <figure>
            <title>Downloaded Files Table</title>

            <mediaobject>
              <imageobject>
                <imagedata align="center" contentwidth="500"
                           fileref="images/download_files.png" />
              </imageobject>
            </mediaobject>
          </figure>
        </listitem>
      </orderedlist>
    </section>

    <section id="delete_log_archive_dev">
      <title>Deleting a Logs Archive from a uCPE device</title>

      <para>Use this option when you want to delete unnecessary collected logs
      on a uCPE device.</para>

      <orderedlist>
        <listitem>
          <para>Access the <emphasis role="bold">Files</emphasis> menu and
          then click the <emphasis role="bold">Download</emphasis>
          button.</para>
        </listitem>

        <listitem>
          <para>Press the <emphasis role="bold">List</emphasis> button.</para>
        </listitem>

        <listitem>
          <para>In the <emphasis role="bold">Device File Listing</emphasis>
          table, select the archive you want to delete from the uCPE
          device.</para>
        </listitem>

        <listitem>
          <para>Press the <emphasis role="bold">Delete</emphasis>
          button.</para>

          <para>The archive will be deleted from the uCPE device and the table
          will be updated.</para>
        </listitem>
      </orderedlist>

      <para>The same can be achieved using these alternative options:</para>

      <orderedlist>
        <listitem>
          <para>Access the <emphasis role="bold">Operations</emphasis> menu
          and select <emphasis role="bold">Delete Debug Log
          Archive</emphasis>.</para>
        </listitem>

        <listitem>
          <para>Provide a file name in the new window.</para>
        </listitem>

        <listitem>
          <para>Press the <emphasis role="bold">Execute</emphasis>
          button.</para>

          <para>A success message is displayed if the file is deleted from the
          uCPE device correctly.</para>
        </listitem>
      </orderedlist>
    </section>

    <section id="delete_archives_ucpem">
      <title>Deleting a Logs Archive from the Enea Edge Management
      application</title>

      <para>This option deletes a logs archive from the Enea Edge Management
      application.</para>

      <orderedlist>
        <listitem>
          <para>Access the <emphasis role="bold">Devices</emphasis> menu, then
          select <emphasis role="bold">Files</emphasis>.</para>
        </listitem>

        <listitem>
          <para>Select the <emphasis role="bold">Downloaded Files</emphasis>
          tab.</para>
        </listitem>

        <listitem>
          <para>Select an archive from the <emphasis role="bold">Downloaded
          Files</emphasis> table.</para>
        </listitem>

        <listitem>
          <para>Click the <emphasis role="bold">Delete</emphasis>
          button.</para>

          <para>The file will be deleted from the Enea Edge Management
          application and the table will be updated.</para>
        </listitem>
      </orderedlist>

      <note>
        <para>Deleting the logs file from the Enea Edge Management application
        does not affect the file located on the uCPE device.</para>
      </note>
    </section>

    <section condition="hidden" id="enable_disable_via_perms">
      <title>Enabling/Disabling the Log Collector via Permissions</title>

      <para>To disable the ability to access/download the uCPE device's
      debug-log files from the Enea Edge Management application, the
      appropriate permissions must be changed:</para>

      <orderedlist>
        <listitem>
          <para>Access the <emphasis role="bold">Security</emphasis> menu,
          then select <emphasis role="bold">Configuration</emphasis>.</para>
        </listitem>

        <listitem>
          <para>Click the <emphasis role="bold">Security Groups</emphasis>
          tab.</para>
        </listitem>

        <listitem>
          <para>Click the desired group.</para>
        </listitem>

        <listitem>
          <para>Click the <emphasis role="bold">Permissions</emphasis> tab on
          the right side.</para>
        </listitem>

        <listitem>
          <para>Click the <emphasis role="bold">Devices</emphasis> tab like in
          the image below.</para>
        </listitem>

        <listitem>
          <para>Change the <emphasis role="bold">Device File
          Management</emphasis> option to <emphasis
          role="bold">none</emphasis> to disable the feature.</para>
        </listitem>
      </orderedlist>

      <figure>
        <title>Device File Management</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center" contentwidth="500"
                       fileref="images/dev_file_mg.png" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section id="download_ucpemg_logs">
      <title>Downloading Enea Edge Management Logs</title>

      <para>Often, sending the Enea Edge Management logs together with
      collected uCPE device logs to the support team provides important
      information for troubleshooting (especially in cases of connectivity
      issues with the uCPE device and error popups).</para>

      <para>Enea Edge Management log files are located in
      <filename>application/logs/</filename> in the Enea Edge Management
      application's installation folder
      (e.g.<filename>/opt/ems/ucpemanager/application/logs</filename>). They
      can be copied from that location, or they can be downloaded using the
      Enea Edge Management GUI by performing the following:</para>

      <orderedlist>
        <listitem>
          <para>Access <emphasis role="bold">Test</emphasis>, then <emphasis
          role="bold">Debug Settings</emphasis> and select the <emphasis
          role="bold">Log Files</emphasis> tab.</para>
        </listitem>

        <listitem>
          <para>Select the desired log file
          (<filename>ucpemanager.log</filename> or
          <filename>watchdog.log</filename>) and press the <emphasis
          role="bold">Download</emphasis> button.</para>
        </listitem>

        <listitem>
          <para>A new (blank) popup window opens and the file is downloaded
          locally. This popup can be closed after the download.</para>
        </listitem>

        <listitem>
          <para>Repeat steps 2. And 3. Until all the desired log files have
          been downloaded</para>
        </listitem>
      </orderedlist>

      <figure>
        <title>Debug Settings</title>

        <mediaobject>
          <imageobject>
            <imagedata align="center" contentwidth="500"
                       fileref="images/debug_settings.png" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>
  </section>

  <section id="log_collect_no_ucpem">
    <title>Log collecting without using the Enea Edge Management
    application</title>

    <para>Log collection from uCPE Devices can also be done when there is no
    Enea Edge Management connection. A SSH connection to the uCPE Device is
    needed for use of the log collector script, which can be found in the uCPE
    Device file system in <literal>/usr/local/enea/</literal>.</para>

    <para>The Log collector script takes relevant information about the system
    and collects it in an archive:</para>

    <programlisting>./log-collector.sh -p &lt;LOG_PATHh&gt; -n &lt;ARCHIVE_NAME&gt;</programlisting>

    <para>Where <literal>-p</literal> is the path where the log archive will
    be saved, and <literal>-n</literal> is the archive name.</para>

    <note>
      <para>If <literal>-p</literal> is not provided, the default path will be
      used: <literal>/var/logcollector</literal>. If <literal>-n</literal> is
      not provided, the default name will be used:
      <filename>log_archive_&lt;timestamp&gt;.tar.gz</filename>.</para>
    </note>

    <para>To access the help menu of the script:</para>

    <programlisting>./log-collector.sh -h</programlisting>
  </section>
</chapter>