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

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="grafana">
  <title>Using Grafana and InfluxDB</title>

  <para><ulink url="https://docs.influxdata.com/influxdb/">InfluxDB</ulink> is
  essentially a time series database process that runs on a server, while
  <ulink url="https://grafana.com/docs/grafana">Grafana</ulink> is a
  visualization tool for time series data. Grafana is a very lightweight
  server-side application, and most of the data monitoring runs in a
  browser.</para>

  <para>For details on version information for these two components, please
  refer to the <ns:include href="../../s_docbuild/olinkdb/pardoc-common.xml"
  xmlns:ns="http://www.w3.org/2001/XInclude"
  xpointer="element(book_enea_edge_telemetry_open_source/1)" />.</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. 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>Internet connection for installing the Docker tool.</para>
        </listitem>

        <listitem>
          <para>Root rights on the CentOS 7 machine.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="docker_steps">
      <title>Setting up Docker for Grafana and InfluxDB</title>

      <para>In order to use the Grafana and InfluxDB containers, the Docker
      tool that runs and manages containers needs to be available on the
      server.</para>

      <para>To install Docker on a CentOS 7 server open a terminal, log into a
      bash shell with the root account and run the following commands:</para>

      <orderedlist>
        <listitem>
          <para><literal>yum check-update</literal></para>
        </listitem>

        <listitem>
          <para><literal>yum install -y yum-utils
          device-mapper-persistent-data lvm2</literal></para>
        </listitem>

        <listitem>
          <para><literal>yum-config-manager --add-repo
          https://download.docker.com/linux/centos/docker-ce.repo</literal></para>
        </listitem>

        <listitem>
          <para><literal>yum install docker</literal></para>
        </listitem>
      </orderedlist>

      <para>In order to deploy the Grafana and InfluxDB images, the Docker
      service needs to be started. To start the Docker service, log into a
      bash shell with the root account and run the following command:
      <literal>systemctl start docker</literal>.</para>

      <note>
        <para>By default, the Docker service is not configured to start at
        boot. In order to configure it to autostart, log into a bash shell
        with the root account and run the following command:
        <literal>systemctl enable docker</literal>. The Grafana and InfluxDB
        images are configured to autostart when the Docker service
        starts.</para>
      </note>
    </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_Edge_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-installerdir&gt;</literal>.</para>
        </listitem>

        <listitem>
          <para>Enter
          <literal>&lt;Telemetry-installerdir&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. Select
          <literal>Both</literal> unless you wish for the Grafana and InfluxDB
          images to be on separate servers.</para>

          <note>
            <para>If an image is already deployed, you will be prompted to
            replace it.</para>

            <para>By default, Grafana is configured for deployment on the same
            server as InfluxDB. Please read the Grafana documentation on how
            to configure it if you wish to deploy the images on separate
            servers.</para>
          </note>
        </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 Edge Management application 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>

      <note>
        <para>The provided Grafana instance by default uses the
        <literal>Username:</literal> <emphasis role="bold">admin</emphasis>
        and <literal>Password:</literal> <emphasis
        role="bold">admin</emphasis>.</para>
      </note>
    </section>
  </section>

  <section id="telemetry_firewall_settings">
    <title>Firewall settings for Grafana and InfluxDB</title>

    <para>If a firewall is running on the machines where Grafana and InfluxDB
    are deployed, this firewall needs to be configured so the required ports
    are enabled.</para>

    <para>To enable the ports, log into a bash shell with the root account and
    perform the following:</para>

    <orderedlist>
      <listitem>
        <para>For InfluxDB, run the following command:</para>

        <programlisting>firewall-cmd --permanent --add-port=25826/udp</programlisting>
      </listitem>

      <listitem>
        <para>For Grafana, run the following command:</para>

        <programlisting>firewall-cmd --permanent --add-port=3000/tcp</programlisting>
      </listitem>
    </orderedlist>
  </section>

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

    <para>Customizing InfluxDB and Grafana parameters can be done in the Enea
    Edge Management GUI by selecting the <emphasis
    role="bold">System</emphasis> menu, then <emphasis
    role="bold">Configuration</emphasis>, 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 public 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 Edge Management application.</entry>

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

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

            <entry>The public 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 Edge Management application
    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 Edge Management
    application 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 Edge Management application. 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>