path: root/doc/book-enea-nfv-access-getting-started/doc/grafana.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="grafana">
  <title>Using Grafana and InfluxDB</title>
  
  <para>InfluxDB is essentially a time series database process that runs on a 
    server, while Grafana is a visualization tool for time series data. 
    Grafana is a very lightweight server-side application, and most of the 
    monitoring runs in a browser.</para>

  <section id="telemetry_deployment">
    <title>Deploying Grafana and InfluxDB</title>
    
    <para>Grafana and InfluxDB can be deployed using images for Docker on linux. 
      These images are provided by Enea along with a deploy script and 
      predefined dashboards.</para>
      
     <para>The Grafana and InfluxDB images can be deployed on the same machine 
       or on separate machines.</para>

    <section id="prereq_deploy">
    <title>Prerequisites for Deploying an Image</title>
      
      <para>The following must be present in order to deploy an image:</para>
    
        <itemizedlist>
          <listitem>
            <para>CentOS 7 Linux.</para>
          </listitem>
          
          <listitem>
            <para>Docker for CentOS 7 installed on the machine and set to 
              <literal>autostart</literal> as a service.</para>
          </listitem>
          
          <listitem>
            <para>Superuser rights on the CentOS 7 machine.</para>
          </listitem>
        </itemizedlist>
     </section>
     
    <section id="deploy_steps">
      <title>Deploying Grafana and InfluxDB</title>
      
        <para>On the CentOS 7 server open a terminal, log into a bash shell
        with the root account and perform the following:</para>
      
        <orderedlist>
          <listitem>
            <para>Extract 
            <filename>Enea_NFV_Access_Telemetry_Deploy_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>.</para>
            
            <para>The directory in which the archive will be unpacked will be
            denoted as: <literal>&lt;Telemetry-installdir&gt;</literal>.</para>
          </listitem>
          
          <listitem>
            <para>Enter <literal>&lt;Telemetry-installdir&gt;</literal>.</para>
          </listitem>
          
          <listitem>
            <para>Run the provided <filename>telemetry_deploy.sh</filename> script.</para>
          </listitem>
          
          <listitem>
            <para>When prompted, select what images you want to deploy.</para>
            
            <para>If an image is already deployed, you will be prompted to replace it.</para>
          </listitem>
          
          <listitem>
            <para>During the InfluxDB deployment, you will be prompted to provide 
              a username and password. These must match the ones configured in the 
              Enea uCPE Manager for Telemetry.
            </para>
            
            <note>
               <para>Changing the InfluxDB username and password requires redeploying 
                 the InfluxDB image.</para>
            </note>
          </listitem>
          
          <listitem>
           <para>Verify the installation by running the command <literal>docker ps -a</literal>.
           The Grafana and InfluxDB containers should be present and have
           the status <literal>Up</literal>.
           </para>
          </listitem>
        </orderedlist>
      </section>
    </section>

  <section id="grafana_settings">
    <title>Setting Grafana and InfluxDB parameters</title>

    <para>Customizing InfluxDB and Grafana parameters can be done by selecting
    <emphasis role="bold">System</emphasis>, then the <emphasis role="bold">Configuration</emphasis> 
      menu, accessing the <emphasis role="bold">Properties</emphasis> tab, and clicking on the 
      <emphasis role="bold">Telemetry</emphasis> tab. The settings that can be changed
    are listed in the table below:</para>

    <table>
      <title>Telemetry settings</title>

      <tgroup cols="3">
        <colspec align="left" colname="1" colwidth="1*" />

        <colspec align="left" colname="2" colwidth="3*" />

        <colspec align="left" colname="3" colwidth="1*" />

        <tbody>
          <row>
            <entry><emphasis role="bold">Field name</emphasis></entry>

            <entry><emphasis role="bold">Description</emphasis></entry>

            <entry><emphasis role="bold">Default value</emphasis></entry>
          </row>

          <row>
            <entry>Grafana Hostname or IP Address</entry>

            <entry>The hostname or IP address where the Grafana instance is
            installed.</entry>

            <entry>no default</entry>
          </row>

          <row>
            <entry>Grafana Port</entry>

            <entry>The port Grafana uses.</entry>

            <entry>3000</entry>
          </row>

          <row>
            <entry>Grafana Dashboard</entry>

            <entry>The dashboard that should be used when opening Grafana
            using the Enea uCPE Manager.</entry>

            <entry>host</entry>
          </row>

          <row>
            <entry>InfluxDB Hostname or IP Address</entry>

            <entry>The hostname or IP address where the InfluxDB database is
            installed.</entry>

            <entry>no default</entry>
          </row>

          <row>
            <entry>InfluxDB Port</entry>

            <entry>The port used for communication between InfluxDB and the
            Telemetry server.</entry>

            <entry>25826</entry>
          </row>

          <row>
            <entry>InfluxDB Username</entry>

            <entry>The username used for encrypting communication between
            InfluxDB and the Telemetry server.</entry>

            <entry>admin0</entry>
          </row>

          <row>
            <entry>InfluxDB Password</entry>

            <entry>The password used for encrypting communication between
            InfluxDB and the Telemetry server.</entry>

            <entry>admin</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>When changing any of the settings in the <emphasis
    role="bold">Telemetry</emphasis> tab, the Enea uCPE Manager will inform all
    uCPE devices of the change if they have telemetry running.</para>

    <figure>
      <title>Telemetry Properties</title>

      <mediaobject>
        <imageobject>
          <imagedata contentwidth="615"
                     fileref="images/telemetry_settings.png" />
        </imageobject>
      </mediaobject>
    </figure>
  </section>

  <section id="telemetry_start_stop">
    <title>Starting and stopping Telemetry</title>

    <para>When a uCPE Device is selected, in the <emphasis
    role="bold">Operations</emphasis> menu, the <emphasis role="bold">Start
    Telemetry</emphasis> and <emphasis role="bold">Stop
    Telemetry</emphasis> options are available.</para>

    <para>When starting Telemetry for a uCPE device, the Enea uCPE Manager sends
    the following information about the InfluxDB:</para>

    <itemizedlist>
      <listitem>
        <para>The IP address and hostname where InfluxDB is installed.</para>
      </listitem>

      <listitem>
        <para>The port used for communication between InfluxDB and the
        Telemetry server.</para>
      </listitem>

      <listitem>
        <para>The credentials used for encrypting communication between
        InfluxDB and the Telemetry server.</para>
      </listitem>
    </itemizedlist>

    <para>These fields are read-only and are populated with the values already
    set in the <emphasis role="bold">System Configuration</emphasis>. If one of the 
      fields is not set or if it does not have the desired value, modify it in the 
      <emphasis role="bold">System Configuration</emphasis>. The password is sent 
      encrypted using the Base64 scheme.</para>

    <figure>
      <title>Telemetry Start Dialog</title>

      <mediaobject>
        <imageobject>
          <imagedata contentwidth="615" fileref="images/telemetry_start.png" />
        </imageobject>
      </mediaobject>
    </figure>

    <para>When the Telemetry status is changed on a uCPE device, a notification is 
      sent to the Enea uCPE Manager. These notifications can be inspected under 
      <emphasis role="bold">Fault</emphasis> found in the 
      <emphasis role="bold">Event</emphasis> menu.</para>
  </section>

  <section id="grafana_launch">
    <title>Launching Grafana</title>

    <para>When a uCPE Device is selected, the <emphasis
    role="bold">Telemetry</emphasis> button is available. Pressing this
    button will open a new window pointing to Grafana. The current uCPE device will
    be selected in Grafana.</para>

    <para>The hostname or IP Address and the port of the Grafana installation
    can be customized by selecting <emphasis role="bold">System</emphasis>, then the 
      <emphasis role="bold">Configuration</emphasis> menu, accessing the 
      <emphasis role="bold">Properties</emphasis> tab, and clicking on the 
      <emphasis role="bold">Telemetry</emphasis> tab. The default dashboard available when
      launching Grafana can be customized as well.</para>
  </section>
</chapter>