.. _Cookbook:

Cookbook
========

This chapter contains recipes for common tasks that can be done in **lnav**.
These recipes can be used as a starting point for your own needs after some
adaptation.


Log Formats
-----------

TBD

Defining a New Format
^^^^^^^^^^^^^^^^^^^^^

TBD


Annotating Logs
---------------

Log messages can be annotated in a couple of different ways in **lnav** to help
you get organized.

Create partitions for Linux boots
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When digging through logs that can be broken up into multiple sections,
**lnav**'s :ref:`partitioning feature<taking_notes>` can be used to keep track
of which section you are in.  For example, if a collection of Linux logs
covered multiple boots, the following script could be used to create partitions
for each boot.  After the partition name is set for the log messages, the
current name will show up in the top status bar next to the current time.

.. literalinclude:: ../../src/scripts/partition-by-boot.lnav
   :language: custsqlite
   :caption: partition-by-boot.lnav
   :linenos:

Tagging SSH log messages
^^^^^^^^^^^^^^^^^^^^^^^^

Log messages can be tagged interactively with the :ref:`:tag<tag>` command or
programmatically using the :ref:`sql-ext`.  This example uses a script to
search for interesting SSH messages and automatically adds an appropriate tag.

.. literalinclude:: ../../example-scripts/tag-ssh-msgs.lnav
   :language: custsqlite
   :caption: tag-ssh-msgs.lnav
   :linenos:

Log Analysis
------------

Most log analysis within **lnav** is done through the :ref:`sql-ext`.  The
following examples should give you some ideas to start leveraging this
functionality.  One thing to keep in mind is that if a query gets to be too
large or multiple statements need to be executed, you can create a
:code:`.lnav` script that contains the statements and execute it using the
:kbd:`\|` command prompt.

Count client IPs in web access logs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To count the occurrences of an IP in web access logs and order the results
from highest to lowest:

.. code-block:: custsqlite

   ;SELECT c_ip, count(*) as hits FROM access_log GROUP BY c_ip ORDER BY hits DESC


Show only lines where a numeric field is in a range
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :ref:`:filter-expr<filter_expr>` command can be used to filter web access
logs to only show lines where the number of bytes transferred to the client is
between 10,000 and 40,000 bytes like so:

.. code-block:: custsqlite

   :filter-expr :sc_bytes BETWEEN 10000 AND 40000


Generating a Report
^^^^^^^^^^^^^^^^^^^

Reports can be generated by writing an **lnav** :ref:`script<scripts>` that
uses SQL queries and commands to format a document.  A basic script can simply
execute a SQL query that is shown in the DB view.  More sophisticated scripts
can use the following commands to generate customized output for a report:

* The :ref:`:echo<echo>` command to write plain text
* :ref:`SQL queries<sql-ext>` followed by a "write" command, like
  :ref:`:write-table-to<write_table_to>`.

.. literalinclude:: ../../example-scripts/report-demo.lnav
   :language: custsqlite
   :caption: report-demo.lnav
   :linenos:


Creating a Runbook
^^^^^^^^^^^^^^^^^^

If you have a collection of lnav scripts, you can create a markdown file
that links to the scripts and use it as a runbook.  Clicking on a link to
a :file:`.lnav` file will open an "Actions" menu with an "Execute" menu
item.  Clicking on "Execute" will launch the script.