summaryrefslogtreecommitdiffstats
path: root/docs/source/usage.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/source/usage.rst101
1 files changed, 97 insertions, 4 deletions
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index d43ed52..df50c7d 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -116,6 +116,68 @@ file.
The binary file is named ``tailer.bin.XXXXXX`` where *XXXXXX* is 6 random digits.
The file is, under normal circumstancies, deleted immediately.
+Command Output
+^^^^^^^^^^^^^^
+
+The output of commands can be captured and displayed in **lnav** using
+the :ref:`:sh<sh>` command or by passing the :option:`-e` option on the
+command-line. The captured output will be displayed in the TEXT view.
+The lines from stdout and stderr are recorded separately so that the
+lines from stderr can be shown in the theme's "error" highlight. The
+time that the lines were received are also recorded internally so that
+the "time-offset" display (enabled by pressing :kbd:`Shift` + :kbd:`T`)
+can be shown and the "jump to slow-down" hotkeys (:kbd:`s` /
+:kbd:`Shift` + :kbd:`S`) work. Since the line-by-line timestamps are
+recorded internally, they will not interfere with timestamps that are
+in the commands output.
+
+Docker Logs
+^^^^^^^^^^^
+
+To make it easier to view
+`docker logs <https://docs.docker.com/engine/reference/commandline/logs/>`_
+within **lnav**, a :code:`docker://` URL scheme is available. Passing
+the container name in the authority field will run the :code:`docker logs`
+command. If a path is added to the URL, then **lnav** will execute
+:code:`docker exec <container> tail -F -n +0 /path/to/file` to try and
+tail the file in the container.
+
+Custom URL Schemes
+^^^^^^^^^^^^^^^^^^
+
+Custom URL schemes can be defined using the :ref:`/tuning/url-schemes<url_scheme>`
+configuration. By adding a scheme name to the tuning configuration along
+with the name of an **lnav** handler script, you can control how the URL is
+interpreted and turned into **lnav** commands. This feature is how the
+`Docker Logs`_ functionality is implemented.
+
+Custom URLs can be passed on the command-line or to the :ref:`:open<open>`
+command. When passed on the command-line, an :code:`:open` command with the
+URL is added to the list of initial commands. When the :code:`:open` command
+detects a custom URL, it checks for the definition in the configuration.
+If found, it will call the associated handler script with the URL as the
+first parameter. The script can parse the URL using the :ref:`parse_url`
+SQL function, if needed. The script should then execute whatever commands
+it needs to open the destination for viewing in **lnav**. For example,
+the docker URL handler uses the :ref:`:sh<sh>` command to run
+:code:`docker logs` with the container.
+
+Using as a PAGER
+^^^^^^^^^^^^^^^^
+
+Setting **lnav** as your :envvar:`PAGER` can have some advantages, like
+basic syntax highlighting and discovering sections in a document. For
+example, when viewing a man page, the current section is displayed in
+the breadcrumb bar and you can jump to a section with the
+:ref:`:goto<goto>` command.
+
+You will probably want to pass the :option:`-q` option to suppress the
+message showing the path to the captured input.
+
+.. prompt:: bash
+
+ export PAGER="lnav -q"
+
Searching
---------
@@ -203,10 +265,41 @@ columns will be included in the table.
Taking Notes
------------
-A few of the columns in the log tables can be updated on a row-by-row basis to
-allow you to take notes. The majority of the columns in a log table are
-read-only since they are backed by the log files themselves. However, the
-following columns can be changed by an :code:`UPDATE` statement:
+As you are looking through logs, you might find that you want to leave some
+notes of your findings. **lnav** can help here by saving information in
+the session without needing to modify the actual log files. Thus, when
+you re-open the files in lnav, the notes will be restored. The following
+types of information can be saved:
+
+:tags: Log messages can be tagged with the :ref:`:tag<tag>` command as a
+ simple way to leave a descriptive mark. The tags attached to a
+ message will be shown underneath the message. You can press
+ :kbd:`u` and :kbd:`Shift` + :kbd:`u` to jump to the next/previous
+ marked line. A regular search will also match tags.
+
+:comments: Free-form text can be attached to a log message with the
+ :ref:`:comment<comment>` command. The comment will be shown
+ underneath the message. If the text contains markdown syntax,
+ it will be rendered to the best of the terminal's ability.
+ You can press :kbd:`u` and :kbd:`Shift` + :kbd:`u` to jump to the
+ next/previous marked line. A regular search will also match the
+ comment text.
+
+:partitions: The log view can be partitioned to provide some context
+ about where you are in a collection of logs. For example, in logs
+ for a test run, partitions could be created with the name for each
+ test. The current partition is shown in the breadcrumb bar and
+ prefixed by the "⊑" symbol. You can select the partition breadcrumb
+ to jump to another partition. Pressing :kbd:`{` and :kbd:`}` will
+ jump to the next/previous partition.
+
+Accessing notes through the SQLite interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The note taking functionality in lnav can also be accessed through the
+log tables exposed through SQLite. The majority of the columns in a log
+table are read-only since they are backed by the log files themselves.
+However, the following columns can be changed by an :code:`UPDATE` statement:
* **log_part** - The "partition" the log message belongs to. This column can
also be changed by the :ref:`:partition-name<partition_name>` command.