README
******

.. image:: https://github.com/aiops/logsight-cli-py/actions/workflows/ci_cd.yml/badge.svg
    :target: https://github.com/aiops/logsight-cli-py/actions/workflows/ci_cd.yml
    :alt: CI/CD

.. image:: https://img.shields.io/pypi/v/logsight-cli-py
    :target: https://pypi.python.org/pypi/logsight-cli-py/
    :alt: Package version

.. image:: https://img.shields.io/pypi/pyversions/logsight-cli-py.svg
    :target: https://pypi.org/project/pytest/

.. image:: https://img.shields.io/pypi/dw/logsight-cli-py.svg
    :target: https://pypi.org/project/logsight-cli-py/
    :alt: Weekly PyPI downloads

..  image:: https://img.shields.io/twitter/follow/logsight.svg?label=logsight&style=flat&logo=twitter&logoColor=4FADFF
    :target: https://twitter.com/logsight
    :alt: logsight.ai on Twitter


Logsight Command Line Interface
-------------------------------

The Logsight Command Line Interface (CLI) is a unified tool to manage your logs.
With this tool, you can manage your logs, applications, tags and execute analytics over logs such as verification.

Commands available include:

+----------------+-------------------------------------------------------------+
| Object         | Description                                                 |
+================+=============================================================+
| Applications   | Create and delete applications                              |
+----------------+-------------------------------------------------------------+
| Users          | Register, activate and delete users (not yet available)     |
+                +-------------------------------------------------------------+
|                | Change and reset password (not yet available)               |
+----------------+-------------------------------------------------------------+
| Logs           | Upload log files                                            |
+                +-------------------------------------------------------------+
|                | Obtain tags                                                 |
+----------------+-------------------------------------------------------------+
| Analytics      | Compare logs                                                |
|                | Detect incidents in logs                                    |
+----------------+-------------------------------------------------------------+


Use Case
------------

Description
==============

+ You have just developed a new version V2 of your application
+ You are not sure if the new version has major bugs that were undetected by your tests
+ You decide to compare the logs generated by your tests for versions V1 and V2
+ Since manually comparing logs is an Herculean task, you submit the logs to logsight.ai for verification
+ logsight.ai returns back a report with various metrics and a deployment risk score
+ Since the risk score is high, you reject the deployment of the new application

.. figure:: img/use_case.png
    :width: 400
    :align: center
    :alt: Use Case for Logsight CLI


For the impatient
==================

Once you have an account with `Logsight.ai`__, you can execute our `Hello World`.

.. code-block:: console

    $ logsight application create --name hadoop_name_node
    app_id: a3de4ae5-a0be-42c5-a6d9-9e9c245831f5

    # copy the <app_id> returned to next command
    $ export LOGSIGHT_APP_ID=a3de4ae5-a0be-42c5-a6d9-9e9c245831f5

    $ logsight log upload samples/hadoop_name_node_v1 --tag v1
    $ logsight log upload samples/hadoop_name_node_v2 --tag v2
    flush_id: cd7bb237-f6b6-4124-925d-9419eca75a48

    # copy <flush_id> returned to next command
    $ logsight compare log --tags v1 v2 --flush_id cd7bb237-f6b6-4124-925d-9419eca75a48
    +---------------------------------+--------------------------------------+
    | KEY                             | VALUE                                |
    +---------------------------------+--------------------------------------+
    ...
    | risk                            | 23                                   |
    | totalLogCount                   | 8332                                 |
    | baselineLogCount                | 4166                                 |
    ...
    +---------------------------------+--------------------------------------+

The risk of deployment is 23%. Thus, it is safe to deploy version v2 of the application.


Installation
------------

The installation has been tested with Mac and Linux operating systems.


Prerequisite
============
You have a `Logsight.ai`_ account with `EMAIL` and `PASSWORD`.

.. __: https://logsight.ai/


Install package
===============

The CLI can can installed using pip from PyPI.

.. code-block:: console

    $ pip install logsight-cli-py


To verify your CLI installation, use the logsight --version command:

.. code-block:: console

    $ logsight --version
    logsight/0.0.12

The output looks like logsight/x.y.z.
If you don't see that output, and installed the Logsight CLI, check if you have an old logsight package on your system.
Uninstall it with these instructions `uninstallation`_.


Configuring Logsight CLI
========================
There are several methods you can use to configure the settings that the Logsight CLI uses when interacting with Logsight.ai service,
i.e. Logsight URL and account API keys. Account API keys can be created in API.

There is a specific load order for what will be used.

Using Logsight Config
======================
You can create a `.logsight` config file to set up your configuration with Logsight server.
The file should be placed in your home directory and contains variables such `EMAIL`, `PASSWORD`, `APP_ID`, etc.

.. code-block:: console

    $ cat ~/.logsight
    [DEFAULT]
    EMAIL = john.miller@zmail.com
    PASSWORD = sawhUz-hanpe4-zaqtyr
    APP_ID = 14082ca2-3e35-4a76-a37c-0d1a48931a19
    DEBUG = False
    JSON = False

Setting the variable APP_ID with a default value is useful if you frequently use the same application and want to avoid passing the Id as a parameter for each command invoked.


Using Environment Variables
===========================
You can also set the variables using your environment.
Environment variables take precedence over config variables.

.. code-block:: console

    $ export LOGSIGHT_EMAIL=john.miller@zmail.com
    $ export LOGSIGHT_PASSWORD=sawhUz-hanpe4-zaqtyr
    $ export LOGSIGHT_APP_ID=07402355-e74e-4115-b21d-4cbf453490d1
    $ export LOGSIGHT_DEBUG=False
    $ export LOGSIGHT_JSON=False

An executable file which can be used to set these environment variables is also available.
You can update it and, afterwards, source it:

.. code-block:: console

    $ source config/logsightrc.sh


Passing Options
===============
If you choose not to use the logsight config file or set environment variables,
you can pass the same values as options as part of any logsight command.

.. code-block:: console

    $ logsight --email john.miller@zmail.com --password sawhUz-hanpe4-zaqtyr applications ls


Examples
--------

The following list provides examples of useful commands:

.. code-block:: console

    $ logsight config
    +----------+--------------------------------------+---------------------------+
    | OPTION   | VALUE                                | SOURCE                    |
    +----------+--------------------------------------+---------------------------+
    | EMAIL    | john.miller@gmail.com                | Environment               |
    | PASSWORD | sawhUz-hanpe4-zaqtyr                 | Environment               |
    | APP_ID   | 14082ca2-3e35-4a76-a37c-0d1a48931a19 | /Users/jmiller/.logsight  |
    | DEBUG    | True                                 | /Users/jmiller/.logsight  |
    | JSON     | False                                | /Users/jmiller/.logsight  |
    +----------+--------------------------------------+---------------------------+

    $ logsight application ls
    +--------------------------------------+------------------+
    | APPLICATION ID                       | NAME             |
    +--------------------------------------+------------------+
    | 7bc44909-a132-40e0-a4e7-1e3caf5b7f45 | hdfs_node        |
    | cb92e882-fd26-41c4-80f0-ff56a8722b8c | node_manager     |
    | 71538838-0296-40fa-8bbc-d91e112a2aab | resource_manager |
    | 83a16a6f-6328-4ef9-b4cc-6afe31f70a91 | name_node        |
    +--------------------------------------+------------------+

    $ logsight application create --name <app name>
    $ logsight application delete --app_id <app id>
    $ logsight application rename --name <app name> --app_id <app id> [Under development]

    $ logsight log upload <file> --tag v1 --app_id <app id>
    $ logsight log tag ls --app_id <app id> [Under development]
    +-------+---------------------+---------------------+
    | TAG   | PERIOD START        | PERIOD END          |
    +-------+---------------------+---------------------+
    | V1    | 2013-10-02T10:50:12 | 2013-10-11T11:12:31 |
    | V2    | 2013-11-08T11:20:14 | 2013-12-02T07:02:09 |
    +-------+---------------------+---------------------+

    $ logsight log status --flush_id --app_id <app id> [Under development]
    +-------+------------+---------------------+---------------------+
    | TAG   | STATUS     | PERIOD START        | PERIOD END          |
    +-------+------------+---------------------+---------------------+
    | V1    | PENDING    | 2013-10-02T10:50:12 | 2013-10-11T11:12:31 |
    +-------+------------+---------------------+---------------------+

    $ logsight log tail --tag <tag> -n 2 --app_id <app id> [Under development]
    2021-12-16 05:16:27,454 INFO org.apache.hadoop.hdfs.DFSUtil: Starting Web-server for hdfs at: http://0.0.0.0:9870
    2021-12-16 05:16:30,464 INFO org.eclipse.jetty.util.log: Logging initialized @924ms to org.eclipse.jetty.util.log.Slf4jLog

    $ logsight compare log --app_id <app id> --tags <tag v1> <tag v2> --flush_id <flush id>
    $ logsight incident log --app_id <app id> --tag <tag>
    $ logsight quality log --tags <tag> --app_id <apps id> [Under development]



Uninstallation
--------------

Uninstall logsight package:

.. code-block:: console

    $ pip uninstall logsight


Availability
------------

The Logsight CLI Python package is deployed to the following external platforms:

+ Test Python Package Index (TestPyPI): `Test PyPI`_
+ Python Package Index (PyPI): PyPI_
+ Documentation: docs_

.. _logsight.ai: https://logsight.ai
.. _test pypi: https://test.pypi.org/search/?q=%22logsight-cli-py%22&o=
.. _pypi: https://pypi.org/search/?q=%22logsight-cli-py%22&o=
.. _docs: https://github.com/aiops/logsight-cli-py