summaryrefslogtreecommitdiffstats
path: root/docs/source
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/_static/theme_overrides.css31
-rw-r--r--docs/source/cli.rst97
-rw-r--r--docs/source/commands.rst4
-rw-r--r--docs/source/conf.py9
-rw-r--r--docs/source/config.rst155
-rw-r--r--docs/source/cookbook.rst9
-rw-r--r--docs/source/formats.rst115
-rw-r--r--docs/source/hotkeys.rst26
-rw-r--r--docs/source/index.rst3
-rw-r--r--docs/source/intro.rst118
-rw-r--r--docs/source/lnav-gantt-1.pngbin0 -> 1575690 bytes
-rw-r--r--docs/source/lnav-gantt-2.pngbin0 -> 1409173 bytes
-rw-r--r--docs/source/lnav-intro-screen.pngbin0 -> 1739591 bytes
-rw-r--r--docs/source/lnav-make-check-log.pngbin0 -> 603097 bytes
-rw-r--r--docs/source/query-results.pngbin35595 -> 409140 bytes
-rw-r--r--docs/source/sqlext.rst43
-rw-r--r--docs/source/sqltab.rst31
-rw-r--r--docs/source/ui.rst179
-rw-r--r--docs/source/usage.rst101
19 files changed, 744 insertions, 177 deletions
diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
index c25d308..39a5db1 100644
--- a/docs/source/_static/theme_overrides.css
+++ b/docs/source/_static/theme_overrides.css
@@ -22,36 +22,7 @@ table.query-results p {
font-size: 0.9em !important;
}
-DL DT:target, :target > H2, :target > H3, span:target + H2, span:target + H3 {
- border: 0 !important;
- border-bottom: 1px solid #d3d381 !important;
- background: #ffc !important;
- /* padding: 1em !important;*/
-}
DL DT {
- border: 0 !important;
- background: inherit !important;
- border-bottom: 1px solid #c3c0ee !important;
- /* display: block !important; */
-}
-
-kbd {
- padding: 0.1em 0.6em;
- border: 1px solid #ccc;
- font-size: 11px;
- font-family: Arial, Helvetica, sans-serif;
- background-color: #f7f7f7;
- color: #333;
- -moz-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
- -webkit-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
- box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
- -moz-border-radius: 3px;
- -webkit-border-radius: 3px;
- border-radius: 3px;
- display: inline-block;
- margin: 0 0.1em 0.1em 0.1em;
- text-shadow: 0 1px 0 #fff;
- line-height: 1.4;
- white-space: nowrap;
+ border-bottom: 1px solid #333 !important;
}
diff --git a/docs/source/cli.rst b/docs/source/cli.rst
index 565e54f..93119e5 100644
--- a/docs/source/cli.rst
+++ b/docs/source/cli.rst
@@ -38,13 +38,19 @@ Options
Execute the given lnav command, SQL query, or lnav script. The
argument must be prefixed with the character used to enter the prompt
- to distinguish between the different types (i.e. ':', ';', '|').
- This option can be given multiple times.
+ to distinguish between the different types (i.e. :code:`:`, :code:`;`,
+ :code:`|`, :code:`/`). This option can be given multiple times.
.. option:: -f <path>
Execute the given command file. This option can be given multiple times.
+.. option:: -e <command-line>
+
+ Execute the given shell command-line and display its output. This is
+ equivalent to executing the :code:`:sh` command and passing the
+ :option:`-N` flag. This option can be given multiple times.
+
.. option:: -I <path>
Add a configuration directory.
@@ -76,23 +82,21 @@ Options
Recursively load files from the given base directories.
-.. option:: -t
-
- Prepend timestamps to the lines of data being read in on the standard input.
-
-.. option:: -w <path>
-
- Write the contents of the standard input to this file.
-
.. option:: -V
Print the version of lnav.
+.. option:: -v
+
+ Print extra information during operations.
+
.. option:: -q
- Do not print the log messages after executing all of the commands.
+ Do not print informational messages.
+.. _management_cli:
+
Management Mode (v0.11.0+)
--------------------------
@@ -107,12 +111,41 @@ Options
Switch to management mode. This must be the first option passed on the
command-line.
+.. option:: -I <path>
+
+ Add a configuration directory.
+
Subcommands
^^^^^^^^^^^
-.. option:: regex101 import <regex101-url> <format-name> [<regex-name>]
+.. option:: config get
- Convert a regex101.com entry into a skeleton log format file.
+ Print out the current configuration as JSON on the standard output.
+
+.. option:: config blame
+
+ Print out the configuration options as JSON-Pointers and the
+ file/line-number where the configuration is sourced from.
+
+.. option:: config file-options <path>
+
+ Print out the options that will be applied to the given file. The
+ options are stored in the :file:`file-options.json` file in the
+ **lnav** configuration directory. The only option available at
+ the moment is the timezone to be used for log message timestamps
+ that do not include a zone. The timezone for a file can be set
+ using the :ref:`:set-file-timezone<set_file_timezone>` command
+ and cleared with the :ref:`:clear-file-timezone<clear_file_timezone>`
+ command.
+
+.. option:: format <format-name> get
+
+ Print information about the given log format.
+
+.. option:: format <format-name> source
+
+ Print the name of the first file that contained this log format
+ definition.
.. option:: format <format-name> regex <regex-name> push
@@ -122,6 +155,22 @@ Subcommands
Pull changes to a regex that was previously pushed to regex101.com .
+.. option:: piper clean
+
+ Remove all of the files that stored data that was piped into **lnav**.
+
+.. option:: piper list
+
+ List all of the data that was piped into **lnav** from oldest to newest.
+ The listing will show the creation time, the URL you can use to reopen
+ the data, and a description of the data. Passing the :option:`-v`
+ option will print out additional metadata that was captured, such as
+ the current working directory of **lnav** and the environment variables.
+
+.. option:: regex101 import <regex101-url> <format-name> [<regex-name>]
+
+ Convert a regex101.com entry into a skeleton log format file.
+
Environment Variables
---------------------
@@ -142,27 +191,27 @@ Environment Variables
.. envvar:: TZ
- The timezone setting is used in some log formats to convert UTC timestamps
- to the local timezone.
+ The timezone setting is used in some log formats to convert timestamps
+ with a timezone to the local timezone.
Examples
--------
- To load and follow the system syslog file:
+To load and follow the system syslog file:
- .. prompt:: bash
+.. prompt:: bash
- lnav
+ lnav
- To load all of the files in :file:`/var/log`:
+To load all of the files in :file:`/var/log`:
- .. prompt:: bash
+.. prompt:: bash
- lnav /var/log
+ lnav /var/log
- To watch the output of make with timestamps prepended:
+To watch the output of make:
- .. prompt:: bash
+.. prompt:: bash
- make 2>&1 | lnav -t
+ lnav -e 'make -j4'
diff --git a/docs/source/commands.rst b/docs/source/commands.rst
index d83a07e..98de0a2 100644
--- a/docs/source/commands.rst
+++ b/docs/source/commands.rst
@@ -68,9 +68,13 @@ an error message in the status bar, like so:
.. note:: The following commands can be disabled by setting the ``LNAVSECURE``
environment variable before executing the **lnav** binary:
+ - :code:`:cd`
+ - :code:`:export-session-to`
- :code:`:open`
- :code:`:pipe-to`
- :code:`:pipe-line-to`
+ - :code:`:redirecto-to`
+ - :code:`:sh`
- :code:`:write-*-to`
This makes it easier to run **lnav** in restricted environments without the
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 3a2d8f2..4f94dba 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -229,7 +229,6 @@ lexers['custsqlite'] = CustSqliteLexer(startinline=True)
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.coverage',
- "sphinx_rtd_theme",
'sphinx_copybutton',
'sphinx-jsonschema',
'sphinx-prompt',
@@ -257,9 +256,9 @@ copyright = u'2023, Tim Stack'
# built documents.
#
# The short X.Y version.
-version = '0.11'
+version = '0.12'
# The full version, including alpha/beta/rc tags.
-release = '0.11.1'
+release = '0.12.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -299,7 +298,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'furo'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -312,7 +311,7 @@ html_theme_options = {
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
-# html_title = None
+html_title = f"lnav v{release}"
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
diff --git a/docs/source/config.rst b/docs/source/config.rst
index 5294e52..d4fc9d5 100644
--- a/docs/source/config.rst
+++ b/docs/source/config.rst
@@ -1,23 +1,34 @@
-
.. _Configuration:
Configuration
=============
-The configuration for **lnav** is stored in the following JSON files in
-:file:`~/.lnav`:
-
-* :file:`config.json` -- Contains local customizations that were done using the
- :code:`:config` command.
-* :file:`configs/default/*.json` -- The default configuration files that are
- built into lnav are written to this directory with :file:`.sample` appended.
- Removing the :file:`.sample` extension and editing the file will allow you to
- do basic customizations.
-* :file:`configs/installed/*.json` -- Contains configuration files installed
- using the :option:`-i` flag (e.g. :code:`$ lnav -i /path/to/config.json`).
-* :file:`configs/*/*.json` -- Other directories that contain :file:`*.json`
- files will be loaded on startup. This structure is convenient for installing
- **lnav** configurations, like from a git repository.
+The configuration for **lnav** is stored in the following JSON files
+where :file:`<lnav-home>` refers to the location in the :envvar:`HOME`
+directory where files are stored, either (:file:`~/.lnav` or
+:file:`~/.config/lnav`):
+
+#. Builtin -- The default configuration is shipped inside the **lnav** binary.
+
+#. :file:`/etc/lnav/configs/*/*.json` -- System-wide configuration files can
+ be installed here to make it available to all users.
+
+#. :file:`<lnav-home>/configs/default/*.json` -- The default configuration
+ files that are built into lnav are written to this directory with :file:`.sample`
+ appended. Removing the :file:`.sample` extension and editing the file will
+ allow you to do basic customizations.
+
+#. :file:`<lnav-home>/configs/*/*.json` -- Other directories that contain :file:`*.json`
+ files will be loaded on startup. This structure is convenient for installing
+ **lnav** configurations, like from a git repository. The :file:`configs/installed`
+ directory is reserved for files that are installed using the :option:`-i`
+ flag (e.g. :code:`$ lnav -i /path/to/config.json`).
+
+#. :file:`-I <path>/configs/*/*.json` -- Include directories passed on the
+ command-line can have a :file:`configs` directory that will also be searched.
+
+#. :file:`<lnav-home>/config.json` -- Contains local customizations that were
+ done using the :code:`:config` command.
A valid **lnav** configuration file must contain an object with the
:code:`$schema` property, like so:
@@ -34,6 +45,14 @@ A valid **lnav** configuration file must contain an object with the
directly. See the :ref:`Log Formats<log_formats>` chapter for more
information.
+.. note::
+
+ Configuration files are read in the above directory order and sorted
+ by path name. The internal configuration is updated as files are
+ parsed, so one file can overwrite the settings from another. You can
+ use the :ref:`Management CLI<management_cli>` to get the final
+ configuration and where the value came from for a particular
+ configuration option.
Options
-------
@@ -115,39 +134,39 @@ You can copy the code block, save it to a file in
definition, see one of the definitions built into **lnav**, like
`monocai <https://github.com/tstack/lnav/blob/master/src/themes/monocai.json>`_.
- .. code-block:: json
-
- {
- "$schema": "https://lnav.org/schemas/config-v1.schema.json",
- "ui": {
- "theme-defs": {
- "example1": {
- "vars": {
- "black": "#2d2a2e"
- },
- "styles": {
- "text": {
- "color": "#f6f6f6",
- "background-color": "$black"
- }
- }
- }
- }
- }
- }
+.. code-block:: json
+
+ {
+ "$schema": "https://lnav.org/schemas/config-v1.schema.json",
+ "ui": {
+ "theme-defs": {
+ "example1": {
+ "vars": {
+ "black": "#2d2a2e"
+ },
+ "styles": {
+ "text": {
+ "color": "#f6f6f6",
+ "background-color": "$black"
+ }
+ }
+ }
+ }
+ }
+ }
Reference
^^^^^^^^^
-.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/([\w\-]+)/properties/vars
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/^([\w\-]+)$/properties/vars
-.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/([\w\-]+)/properties/styles
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/^([\w\-]+)$/properties/styles
-.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/([\w\-]+)/properties/syntax-styles
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/^([\w\-]+)$/properties/syntax-styles
-.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/([\w\-]+)/properties/status-styles
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/^([\w\-]+)$/properties/status-styles
-.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/([\w\-]+)/properties/log-level-styles
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/theme-defs/patternProperties/^([\w\-]+)$/properties/log-level-styles
.. _theme_style:
@@ -198,7 +217,7 @@ to the key.
Reference
^^^^^^^^^
-.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/keymap-defs/patternProperties/([\w\-]+)
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/ui/properties/keymap-defs/patternProperties/^([\w\-]+)$
Log Handling
@@ -208,6 +227,18 @@ The handling of logs is largely determined by the
:ref:`log file formats<log_formats>`, this section covers options that are not
specific to a particular format.
+Timezone Conversion (v0.12.0+)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Log messages that have a numeric timezone, like :code:`-03:00` or :code:`Z`
+for UTC, will be converted to the local timezone as given by the :envvar:`TZ`
+environment variable. For example, a timestamp ending in `-03:00` will be treated
+as three hours behind UTC and then adjusted to the local timezone.
+
+This behavior can be disabled by setting the
+:code:`/log/date-time/convert-zoned-to-local` configuration property to
+:code:`false`.
+
Watch Expressions (v0.11.0+)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -243,10 +274,44 @@ From there, you can create a SQLite trigger on the :code:`lnav_events` table
that will examine the event contents and perform an action. See the
:ref:`Events` section for more information on handling events.
+Annotations (v0.12.0+)
+^^^^^^^^^^^^^^^^^^^^^^
+
+Annotations are content generated by a script for a given log message and
+displayed along with the message, like comments and tags. Since the script
+is run asynchronously, it can do complex analysis without delaying loading
+or interrupting the viewing experience. An annotation is defined by a
+condition and a handler in the **lnav** configuration. The condition is
+tested against a log message to determine if the annotation is applicable.
+If it is, the handler script will be executed for that log message when
+the user runs the :ref:`:annotate<annotate>` command.
+
+Conditions are SQLite expressions like the ones passed to
+:ref:`:filter-expr<filter_expr>` where the expression is appended to
+:code:`SELECT 1 WHERE`. The expression can use bound variables that
+correspond to the columns that would be in the format table and are
+prefixed by a colon (:code:`:`). For example, the standard
+:code:`log_opid` table column can be access by using :code:`:log_opid`.
+
+.. note:: The expression is executed with bound variables because it
+ can be applied to log messages from multiple formats. Writing an
+ expression that could handle different formats would be more
+ challenging. In this approach, variables for log message fields
+ that are not part of a format will evaluate to :code:`NULL`.
+
+Handlers are executable script files that should be co-located with
+the configuration file that defined the annotation. The handler will
+be executed and a JSON object with log message data fed in on the
+standard input. The handler should then generate the annotation
+content on the standard output. The output is treated as Markdown,
+so the content can be styled as desired.
+
Reference
^^^^^^^^^
-.. jsonschema:: ../schemas/config-v1.schema.json#/properties/log/properties/watch-expressions/patternProperties/([\w\-]+)
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/log/properties/watch-expressions/patternProperties/^([\w\.\-]+)$
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/log/properties/annotations/patternProperties/^([\w\.\-]+)$
+
.. _tuning:
@@ -261,6 +326,8 @@ command.
.. jsonschema:: ../schemas/config-v1.schema.json#/properties/tuning/properties/clipboard
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/tuning/properties/piper
+
.. jsonschema:: ../schemas/config-v1.schema.json#/definitions/clip-commands
.. jsonschema:: ../schemas/config-v1.schema.json#/properties/tuning/properties/file-vtab
@@ -268,3 +335,7 @@ command.
.. jsonschema:: ../schemas/config-v1.schema.json#/properties/tuning/properties/logfile
.. jsonschema:: ../schemas/config-v1.schema.json#/properties/tuning/properties/remote/properties/ssh
+
+.. _url_scheme:
+
+.. jsonschema:: ../schemas/config-v1.schema.json#/properties/tuning/properties/url-scheme
diff --git a/docs/source/cookbook.rst b/docs/source/cookbook.rst
index 3eb0ffd..9523235 100644
--- a/docs/source/cookbook.rst
+++ b/docs/source/cookbook.rst
@@ -1,4 +1,3 @@
-
.. _Cookbook:
Cookbook
@@ -69,9 +68,9 @@ 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
+.. code-block:: custsqlite
- ;SELECT c_ip, count(*) as hits FROM access_log GROUP BY c_ip ORDER BY hits DESC
+ ;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
@@ -81,9 +80,9 @@ 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
+.. code-block:: custsqlite
- :filter-expr :sc_bytes BETWEEN 10000 AND 40000
+ :filter-expr :sc_bytes BETWEEN 10000 AND 40000
Generating a Report
diff --git a/docs/source/formats.rst b/docs/source/formats.rst
index b30713d..d57add1 100644
--- a/docs/source/formats.rst
+++ b/docs/source/formats.rst
@@ -1,7 +1,11 @@
.. _log_formats:
+***********
Log Formats
-===========
+***********
+
+Built-in Formats
+================
Log files loaded into **lnav** are parsed based on formats defined in
configuration files. Many
@@ -19,6 +23,9 @@ The following log formats are built into **lnav**:
:widths: 8 5 20
:file: format-table.csv
+XSV Formats
+-----------
+
In addition to the above formats, the following self-describing formats are
supported:
@@ -33,6 +40,24 @@ supported:
self-describing, so **lnav** will read the header to determine the shape of
the file.
+JSON-lines
+----------
+
+Logs encoded as `JSON-lines <https://jsonlines.org>`_ can be parsed and
+pretty-printed in lnav by creating a log format file. The format file
+is a bit simpler to create since it doesn't require a regular expression
+to match plain text. Instead, the format defines the relevant fields
+and provides a :code:`line-format` array that specifies how the fields
+in the JSON object should be displayed.
+
+See the following formats that are built into lnav as examples:
+
+* `cloudflare_log.json <https://github.com/tstack/lnav/blob/master/src/formats/cloudflare_log.json>`_
+* `github_events_log.json <https://github.com/tstack/lnav/blob/master/src/formats/github_events_log.json>`_
+
+logfmt
+------
+
There is also basic support for the `logfmt <https://brandur.org/logfmt>`_
convention for formatting log messages. Files that use this format must
have the entire line be key/value pairs and the timestamp contained in a
@@ -41,9 +66,8 @@ quite follow this formatting, but wraps logfmt data with another recognized
format, you can use the :ref:`logfmt2json` SQL function to convert the data
into JSON for further analysis.
-
Defining a New Format
----------------------
+=====================
New log formats can be defined by placing JSON configuration files in
subdirectories of the :file:`/etc/lnav/formats` and :file:`~/.lnav/formats/`
@@ -55,7 +79,7 @@ modify existing ones. Format directories can also contain '.sql' and '.lnav'
script files that can be used automate log file analysis.
Creating a Format Using Regex101.com (v0.11.0+)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------------------
For plain-text log files, the easiest way to create a log format definition is
to create the regular expression that recognizes log messages using
@@ -81,7 +105,7 @@ default to :code:`string`, but you'll want to change them to the appropriate
type.
Format File Reference
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
An **lnav** format file must contain a single JSON object, preferably with a
:code:`$schema` property that refers to the
@@ -133,6 +157,30 @@ object with the following fields:
:json: True if each log line is JSON-encoded.
+:converter: An object that describes how an input file can be detected and
+ then converted to a form that can be interpreted by **lnav**. For
+ example, a PCAP file is in a binary format that cannot be handled natively
+ by **lnav**. However, a PCAP file can be converted by :file:`tshark`
+ into JSON-lines that can be handled by **lnav**. So, this configuration
+ describes how the input file format can be detected and converted. See
+ `Automatic File Conversion`_ for more information.
+
+ :header: An object that describes how to match the header of the input
+ file.
+
+ :expr: An object that contains SQLite expressions that can be used to
+ check if the input file's header is of this type. The property
+ name is the name of the expression and the value is the expression.
+ The expression is evaluated with the following variables:
+
+ :\:header: The hex-encoded version of the header content.
+
+ :\:filepath: The path to the input file.
+
+ :size: The minimum size of header that is needed to do the match.
+
+ :command: The command to execute to convert the input file.
+
:line-format: An array that specifies the text format for JSON-encoded
log messages. Log files that are JSON-encoded will have each message
converted from the raw JSON encoding into this format. Each element
@@ -179,6 +227,9 @@ object with the following fields:
:truncate: Truncates any text past the maximum width.
:dot-dot: Cuts out the middle of the text and replaces it with two
dots (i.e. '..').
+ :last-word: Removes all but the last word in text with dot, dash,
+ forward-slash, or colon separators. For example, "com.example.foo"
+ would be shortened to "foo".
(v0.8.2+)
:timestamp-format: The timestamp format to use when displaying the time
@@ -319,6 +370,19 @@ object with the following fields:
:glob: A glob pattern to check against the log files read by lnav.
+:partitions: This object contains a description of partitions that should
+ automatically be created in the log view.
+
+ :pattern: The regular expression evaluated over a line in the log file as
+ it is read in. If there is a match, the log message the line is a part
+ of will be used as the start of the partition. The name of the
+ partition will be taken from any captures in the regex.
+ :paths: This array contains objects that define restrictions on the file
+ paths in which partitions will be created. The objects in this array
+ can contain:
+
+ :glob: A glob pattern to check against the log files read by lnav.
+
.. _format_sample:
:sample: A list of objects that contain sample log messages. All formats
@@ -455,6 +519,15 @@ hash are treated as comments. The following variables are defined in a script:
The arguments passed to the script.
+.. envvar:: LNAV_HOME_DIR
+
+ The path to the directory where the user's **lnav** configuration is stored.
+
+.. envvar:: LNAV_WORK_DIR
+
+ The path to the directory where **lnav** caches files, like archives that
+ have been unpacked or piper captures.
+
Remember that you need to use the :ref:`:eval<eval>` command when referencing
variables in most **lnav** commands. Scripts can provide help text to be
displayed during interactive usage by adding the following tags in a comment
@@ -482,7 +555,7 @@ header:
:eval :filter-out ${pattern}
VSCode Extension
-^^^^^^^^^^^^^^^^
+----------------
The `lnav VSCode Extension <https://marketplace.visualstudio.com/items?itemName=lnav.lnav>`_
can be installed to add syntax highlighting to lnav scripts.
@@ -533,7 +606,7 @@ Executing the format file should then install it automatically:
.. _format_order:
Format Order When Scanning a File
----------------------------------
+=================================
When **lnav** loads a file, it tries each log format against the first 15,000
lines [#]_ of the file trying to find a match. When a match is found, that log
@@ -559,3 +632,31 @@ will win.
.. [#] The maximum number of lines to check can be configured. See the
:ref:`tuning` section for more details.
+
+Automatic File Conversion
+=========================
+
+File formats that are not naturally understood by **lnav** can be
+automatically detected and converted to a usable form using the
+:code:`converter` property. For example, PCAP files can be
+detected and converted to a JSON-lines form using :code:`tshark`.
+The conversion process works as follows:
+
+#. The first 1024 bytes of the file are read, if available.
+#. This header is converted into a hex string.
+#. For each log format that has defined a :code:`converter`,
+ every "header expression" is evaluated to see if there is a
+ match. The header expressions are SQLite expressions where
+ the following variables are defined:
+
+ :\:header: A string containing the header as a hex string.
+
+ :\:filepath: The path to the file.
+
+#. If a match is found, the converter script defined in the
+ log format will be invoked and passed the format name and
+ path to the file as arguments. The script should write
+ the converted form of the input file on its standard output.
+ Any errors should be written to the standard error.
+#. The log format will be associated with the original file will
+ be used to interpret the converted file.
diff --git a/docs/source/hotkeys.rst b/docs/source/hotkeys.rst
index 4bad1d9..7b065e7 100644
--- a/docs/source/hotkeys.rst
+++ b/docs/source/hotkeys.rst
@@ -7,6 +7,23 @@ This reference covers the keys used to control **lnav**. Consult the `built-in
help <https://github.com/tstack/lnav/blob/master/src/help.txt>`_ in **lnav** for
a more detailed explanation of each key.
+Global
+------
+
+.. list-table::
+ :header-rows: 1
+ :widths: 6 20
+
+ * - Keypress
+ - Command
+
+ * - :kbd:`Ctrl` + :kbd:`C`
+ - If the focused line is from a file connected to an open pipe (the "↻"
+ icon will be next to the file name), a SIGINT will be sent to the
+ child process. Otherwise, **lnav** will quickly exit. If **lnav**
+ seems to be stuck in a loop, pressing :kbd:`Ctrl` + :kbd:`C` three
+ times will trigger an abort exit.
+
Spatial Navigation
------------------
@@ -148,9 +165,10 @@ status bar.
* - Keypress
- Description
+ * - :kbd:`\``
+ - Focus on the breadcrumb bar.
* - :kbd:`ENTER`
- - Focus on the breadcrumb bar. Or, if the bar is currently focused,
- accept the selected value and drop focus.
+ - If the bar is currently focused, accept the selected value and drop focus.
* - :kbd:`Escape`
- Drop focus on the breadcrumb bar.
* - :kbd:`←`
@@ -223,7 +241,9 @@ Display
* - :kbd:`Shift` + :kbd:`p`
- Switch to/from the pretty-printed view of the displayed log or text files
* - :kbd:`Shift` + :kbd:`t`
- - Display elapsed time between lines
+ - Display the elapsed time from a bookmark to a given line. In the TEXT view,
+ this only works for content that was captured from stdin or a :code:`:sh`
+ command.
* - :kbd:`t`
- Switch to/from the text file view
* - :kbd:`i`
diff --git a/docs/source/index.rst b/docs/source/index.rst
index d94c0eb..29d2be1 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -2,7 +2,8 @@ Welcome to lnav's documentation!
================================
The `Log File Navigator <http://lnav.org>`_ (**lnav**) is an advanced log file
-viewer for the console.
+viewer for the console. If you have a bunch of log files that you need to
+look through to find issues, **lnav** is the tool for you.
Contents:
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index 96b0612..28172a1 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -11,16 +11,12 @@ navigate through your logs using a variety of :ref:`hotkeys<hotkeys>`.
for doing things like applying filters, tagging messages, and more. You can
then analyze your log messages using the :ref:`sql-ext`.
-Development
------------
+.. figure:: lnav-intro-screen.png
+ :align: center
+ :alt: Screenshot of lnav showing a mix of syslog and web access_log messages.
-Development of lnav is hosted on `GitHub <https://github.com/tstack/lnav/>`_.
+ Screenshot of **lnav** viewing syslog and web access_log messages.
-`Issues <https://github.com/tstack/lnav/issues>`_ should be used for bugs
-and feature requests.
-
-`Discussions <https://github.com/tstack/lnav/discussions>`_ should be used
-for asking questions and sharing tips.
Downloads
---------
@@ -28,34 +24,7 @@ Downloads
Binaries and source code for lnav can be downloaded from the
`releases page <https://github.com/tstack/lnav/releases>`_.
-When building from source, follow the steps below.
-
-Dependencies
-^^^^^^^^^^^^
-
-When compiling from source, the following dependencies are required:
-
-* `NCurses <http://www.gnu.org/s/ncurses/>`_
-* `PCRE2 <http://www.pcre.org>`_
-* `SQLite <http://www.sqlite.org>`_
-* `ZLib <http://wwww.zlib.net>`_
-* `Bzip2 <http://www.bzip.org>`_
-* `Readline <http://www.gnu.org/s/readline>`_
-* `libcurl <https://curl.haxx.se>`_
-* `libarchive <https://libarchive.org>`_
-
-Installation
-^^^^^^^^^^^^
-
-Check the `downloads page <http://lnav.org/downloads>`_ to see if there are
-packages for your operating system. To compile from source, use the following
-commands:
-
-.. prompt:: bash
-
- ./configure
- make
- sudo make install
+When building from source, follow the steps in :ref:`development`.
Viewing Logs
@@ -129,6 +98,7 @@ command can be used to the change the theme:
The builtin themes are:
`default <https://github.com/tstack/lnav/blob/master/src/themes/default-theme.json>`_,
+`dracula <https://github.com/tstack/lnav/blob/master/src/themes/dracula.json>`_,
`eldar <https://github.com/tstack/lnav/blob/master/src/themes/eldar.json>`_,
`grayscale <https://github.com/tstack/lnav/blob/master/src/themes/grayscale.json>`_,
`monocai <https://github.com/tstack/lnav/blob/master/src/themes/monocai.json>`_,
@@ -143,16 +113,33 @@ To create or customize a theme, consult the :ref:`themes` section.
Cursor Mode (v0.11.2+)
^^^^^^^^^^^^^^^^^^^^^^
-The default mode for scrolling in **lnav** is to move the contents of the
-main view when the arrow keys are pressed. Any interactions, such as
-jumping to a search hit, are then focused on the top line in the view.
-Alternatively, you can enable "cursor" mode where there is a cursor line
-in the view that is moved by the arrow keys and other interactions. You
-can enable cursor mode with the following command:
+The default mode for scrolling in **lnav** is "cursor" mode where
+there is a cursor line in the view that is moved by the arrow keys
+and other interactions. Any interactions, such as jumping to a
+search hit, are then focused on that line.
+
+Alternatively, you can enable "top" mode where the contents of the
+main view are moved when the arrow keys are pressed. Any
+interactions, such as jumping to a search hit, are then focused
+on the top line in the view. You can change to "top" mode with
+the following command:
+
+.. code-block:: lnav
+
+ :config /ui/movement/mode top
+
+
+Mouse Support (v0.12.2+)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Mouse support can be enabled temporarily by pressing :kbd:`F2`
+and can be set as the default by executing the following command:
.. code-block:: lnav
- :config /ui/movement/mode cursor
+ :config /ui/mouse/mode enabled
+
+See :ref:`ui_mouse` for more details.
Log Formats
^^^^^^^^^^^
@@ -162,3 +149,48 @@ parse the log messages using a log format definition. There are many log
formats builtin and **lnav** will automatically determine the best format to
use. In case your log file is not recognized, consult the :ref:`log_formats`
section for information on how to create a format.
+
+.. _development:
+
+Development
+-----------
+
+Development of lnav is hosted on `GitHub <https://github.com/tstack/lnav/>`_.
+
+`Issues <https://github.com/tstack/lnav/issues>`_ should be used for bugs
+and feature requests.
+
+`Discussions <https://github.com/tstack/lnav/discussions>`_ should be used
+for asking questions and sharing tips.
+
+Dependencies
+^^^^^^^^^^^^
+
+When compiling from source, the following dependencies are required:
+
+* `NCurses <http://www.gnu.org/s/ncurses/>`_
+* `PCRE2 <http://www.pcre.org>`_
+* `SQLite <http://www.sqlite.org>`_
+* `ZLib <http://wwww.zlib.net>`_
+* `Bzip2 <http://www.bzip.org>`_
+* `Readline <http://www.gnu.org/s/readline>`_
+* `libcurl <https://curl.haxx.se>`_
+* `libarchive <https://libarchive.org>`_
+
+Installation
+^^^^^^^^^^^^
+
+Check the `downloads page <http://lnav.org/downloads>`_ to see if there are
+packages for your operating system. To compile from source, use the following
+commands:
+
+.. note::
+
+ Run :code:`./autogen.sh` if compiling from the git repository.
+
+.. prompt:: bash
+
+ ./configure
+ make
+ sudo make install
+
diff --git a/docs/source/lnav-gantt-1.png b/docs/source/lnav-gantt-1.png
new file mode 100644
index 0000000..306187c
--- /dev/null
+++ b/docs/source/lnav-gantt-1.png
Binary files differ
diff --git a/docs/source/lnav-gantt-2.png b/docs/source/lnav-gantt-2.png
new file mode 100644
index 0000000..90bf8c1
--- /dev/null
+++ b/docs/source/lnav-gantt-2.png
Binary files differ
diff --git a/docs/source/lnav-intro-screen.png b/docs/source/lnav-intro-screen.png
new file mode 100644
index 0000000..39d8129
--- /dev/null
+++ b/docs/source/lnav-intro-screen.png
Binary files differ
diff --git a/docs/source/lnav-make-check-log.png b/docs/source/lnav-make-check-log.png
new file mode 100644
index 0000000..68ac351
--- /dev/null
+++ b/docs/source/lnav-make-check-log.png
Binary files differ
diff --git a/docs/source/query-results.png b/docs/source/query-results.png
index 14ae5b8..8343d71 100644
--- a/docs/source/query-results.png
+++ b/docs/source/query-results.png
Binary files differ
diff --git a/docs/source/sqlext.rst b/docs/source/sqlext.rst
index 221b100..3b0ee75 100644
--- a/docs/source/sqlext.rst
+++ b/docs/source/sqlext.rst
@@ -47,6 +47,14 @@ and maximum number of bytes returned by the server, grouped by IP address:
;SELECT c_ip, avg(sc_bytes), max(sc_bytes) FROM access_log GROUP BY c_ip
+.. note::
+
+ For reference, the PRQL query would look like this:
+
+ .. code-block:: elm
+
+ from access_log | stats.by c_ip {average sc_bytes, max sc_bytes}
+
After pressing :kbd:`Enter`, SQLite will execute the query using **lnav**'s
virtual table implementation to extract the data directly from the log files.
Once the query has finished, the main window will switch to the DB view to
@@ -71,6 +79,39 @@ The DB view has the following display features:
the `jget`_ function.
+PRQL Support (v0.12.1+)
+-----------------------
+
+`PRQL <https://prql-lang.org>`_ is an alternative database query language
+that compiles to SQLite. You can enter PRQL in the database query prompt
+and lnav will switch accordingly. A major advantage of using PRQL is that
+lnav can show previews of the results of the pipeline stages and provide
+better tab completion options.
+
+A PRQL query starts with the :code:`from` keyword that specifies the table
+to use as a data source. The next stage of a pipeline is started by
+entering a pipe symbol (:code:`|`) followed by a
+`PRQL transform <https://prql-lang.org/book/reference/stdlib/transforms/index.html>`_.
+As you build the query in the prompt, lnav will display any relevant
+help and preview for the current and previous stages of the pipeline.
+
+The following is a screenshot of lnav viewing a web access log with a
+query in progress:
+
+.. figure:: ../assets/images/lnav-prql-preview.png
+ :align: center
+
+ Screenshot of a PRQL query in progress
+
+The top half of the window is the usual log message view. Below that is
+the online help panel showing the documentation for the :code:`stats.count_by`
+PRQL function. lnav will show the help for what is currently under the
+cursor. The next panel shows the preview data for the pipeline stage
+that precedes the stage where the cursor is. In this case, the
+results of :code:`from access_log`, which is the contents of the access
+log table. The second preview window shows the result of the
+pipeline stage where the cursor is located.
+
Log Tables
----------
@@ -105,6 +146,8 @@ The following columns are builtin and included in a :code:`SELECT *`:
an :code:`UPDATE` or the :ref:`:comment<comment>` command.
:log_tags: A JSON list of tags for the message. This column can be changed
by an :code:`UPDATE` or the :ref:`:tag<tag>` command.
+ :log_annotations: A JSON object of annotations for this message.
+ This column is populated by the :ref:`:annotate<annotate>` command.
:log_filters: A JSON list of filter IDs that matched this message
The following columns are builtin and are hidden, so they will *not* be
diff --git a/docs/source/sqltab.rst b/docs/source/sqltab.rst
index 2531390..299ba2b 100644
--- a/docs/source/sqltab.rst
+++ b/docs/source/sqltab.rst
@@ -7,6 +7,7 @@ In addition to the tables generated for each log format, **lnav** includes
the following tables/views:
* `environ`_
+* `fstat(<path|pattern>)`_
* `lnav_events`_
* `lnav_file`_
* `lnav_file_metadata`_
@@ -31,7 +32,7 @@ by executing the '.schema' SQL command, like so::
environ
-------
-The **environ** table gives you access to the **lnav** process' environment
+The :code:`environ` table gives you access to the **lnav** process' environment
variables. You can :code:`SELECT`, :code:`INSERT`, and :code:`UPDATE`
environment variables, like so:
@@ -55,6 +56,19 @@ named "FILENAME" and then open it in **lnav** by referencing it with
:open $FILENAME
+fstat(<path|pattern>)
+---------------------
+
+The :code:`fstat` table-valued function provides access to the local
+file system. The function takes a file path or a glob pattern and
+returns the results of :code:`lstat(2)` for the matching files. If
+the parameter is a pattern that matches nothing, no rows will be
+returned. If the parameter is a path for a non-existent file, a
+row will be returned with the :code:`error` column set and the
+stat columns as :code:`NULL`. To read the contents of a file, you
+can :code:`SELECT` the hidden :code:`data` column.
+
+
.. _table_lnav_events:
lnav_events
@@ -81,12 +95,22 @@ following columns are available in this table:
:device: The device the file is stored on.
:inode: The inode for the file on the device.
:filepath: If this is a real file, it will be the absolute path. Otherwise,
- it is a symbolic name. If it is a symbolic name, it can be UPDATEd so that
- this file will be considered when saving and loading session information.
+ it is a symbolic name. If it is a symbolic name, it can be UPDATEd
+ so that this file will be considered when saving and loading session
+ information.
+ :mimetype: The detected MIME type of the file.
+ :content_id: The hash of some unique content in the file.
:format: The log file format for the file.
:lines: The number of lines in the file.
:time_offset: The millisecond offset for timestamps. This column can be
UPDATEd to change the offset of timestamps in the file.
+ :options_path: Options can be applied to files based on a path or glob
+ pattern. If this file matches a set of options, the matching path/pattern
+ is available in this column and the actual options themselves are in the
+ :code:`options` column.
+ :options: The options that are applicable to this file. Currently, the
+ only options available are for the timezone set by the
+ :ref:`:set-file-timezone<set_file_timezone>` command.
lnav_file_metadata
------------------
@@ -169,6 +193,7 @@ available in this table:
:top_meta: A JSON object that contains metadata related to the top line
in the view.
:selection: The number of the line that is focused for selection.
+:options: A JSON object that contains optional settings for this view.
lnav_views_echo
---------------
diff --git a/docs/source/ui.rst b/docs/source/ui.rst
index a718d06..b2de5b7 100644
--- a/docs/source/ui.rst
+++ b/docs/source/ui.rst
@@ -8,7 +8,7 @@ with status bars above and below, and the interactive prompt as the last line.
.. figure:: lnav-ui.png
:align: center
- :alt: Screenshot of lnav showing a mix of syslog and web access_log messages.
+ :figwidth: 90%
Screenshot of **lnav** viewing syslog and web access_log messages.
@@ -26,11 +26,11 @@ times in the views.
**lnav** provides many operations to work with the log/text data in the
main view. For example, you can add comments and tags to log messages.
-By default, the top line is used as the reference point to edit the
+The highlighted cursor line is used as the reference point to edit the
comment or tags. Alternatively, you can press :kbd:`Ctrl` + :kbd:`x`
-to switch to "cursor" mode where the "focused" line is highlighted and
-most operations now work with that line. When in "cursor" mode, the
-:kbd:`↑` and :kbd:`↓` keys now move the focused line instead of scrolling
+to switch to "top" mode where the "focused" line is the top line in the
+view and most operations now work with that line. When in "cursor" mode,
+the :kbd:`↑` and :kbd:`↓` keys now move the focused line instead of scrolling
the view. Jumping to bookmarks, like errors, will also move the focused
line instead of moving the next error to the top of the view.
@@ -173,7 +173,9 @@ LOG
^^^
The log view displays the log messages from any loaded log files in time
-order. This view will be shown by default if any log messages are available.
+order. This view will be shown by default if any log files were detected.
+If plain text files were also loaded, they will be available in the TEXT
+view, which you can switch to by pressing :kbd:`t`.
On color displays, the log messages will be highlighted as follows:
@@ -194,11 +196,18 @@ On color displays, the log messages will be highlighted as follows:
:config /ui/theme grayscale
+Timestamps in log messages will be rewritten to the local timezone (or the
+timezone specified by :envvar:`TZ`) automatically if they include a
+timezone component. If a file's timestamps do not include a timezone, they
+will be treated as if they are from the local zone. You can change the zone
+to use for these types of files using the
+:ref:`:set-file-timezone<set_file_timezone>` command.
+
.. note::
If a log message has a timestamp that is out-of-order with its neighboring
messages, the timestamp will be highlighted in yellow. When one of these
- messages is at the top of the log view, an overlay will display the
+ messages is focused, an overlay will display the
difference between the "actual time" and the "received time". The "actual
time" is the original textual timestamp. The "received time" is the time
of an earlier message that is larger than this log message's time.
@@ -221,6 +230,10 @@ These crumbs are interactive and can be used to navigate to different parts
of the log view. For example, selecting a different value in the log format
crumb will jump to the first message with that format.
+The file crumb will show a "↻" icon if the file is from the output of a FIFO,
+:code:`:sh` command, or data that was piped into the standard input. When
+the pipe is closed, the icon will disappear.
+
TEXT
^^^^
@@ -230,16 +243,39 @@ Press :kbd:`t` to switch to the text view. While in the text view, you can
press :kbd:`f` or :kbd:`Shift` + :kbd:`F` to switch to the next / previous
text file.
+The breadcrumb bar will show the name of the file and any structure that was
+discovered in the content. The file crumb will show a "↻" icon if the file
+is from the output of a FIFO, :code:`:sh` command, or data that was piped
+into the standard input. When the pipe is closed, the icon will disappear.
+
+If the content is piped into lnav through standard input, a FIFO, or a
+:code:`:sh` command, the time that lines are received are recorded. You
+can press :kbd:`Shift` + :kbd:`T` to view the elapsed time like in the
+LOG view. The breadcrumb bar will also show the received time of the
+focused line after the file name crumb. If the output being shown is from
+a :code:`:sh` command, you can press :kbd:`Ctrl` + :kbd:`C` to send a
+SIGINT to the child process without killing **lnav** itself.
+
+.. figure:: lnav-make-check-log.png
+ :align: center
+ :figwidth: 90%
+
+ Screenshot of the TEXT view showing the output of :code:`sh make check`.
+ Each line is timestamped internally when it was received so it's
+ possible to view how long each test is taking to run. The "↻" icon
+ next to the file name in the breadcrumb bar means that the make is
+ still running.
+
Markdown
""""""""
Files with an :code:`.md` (or :code:`.markdown`) extension will be treated as
Markdown files and rendered separately.
- .. figure:: lnav-markdown-example.png
- :align: center
+.. figure:: lnav-markdown-example.png
+ :align: center
- Viewing the **lnav** :file:`README.md` file.
+ Viewing the **lnav** :file:`README.md` file.
DB
@@ -269,6 +305,61 @@ can also press :kbd:`Shift` + :kbd:`i` to toggle the histogram view
while synchronizing the top time. While in the histogram view,
pressing :kbd:`z` / :kbd:`Shift` + :kbd:`z` will zoom in/out.
+GANTT
+^^^^^
+
+.. note:: This feature is available in v0.12.0+.
+
+.. figure:: lnav-gantt-1.png
+ :align: center
+
+ Screenshot of the Gantt chart view when viewing logs from the
+ VMWare Update Manager. Most rows show API requests as they
+ are received and processed.
+
+The Gantt Chart view visualizes operations over time. The operations
+are identified by the "opid" field defined in the log format. In the
+view, there is a header that shows the overall time span, the
+narrowed time span around the focused line, and the column headers.
+Each row in the view shows the following:
+
+* The duration of the operation
+* Sparklines showing the number of errors and warnings relative to the
+ total number of messages associated with the OPID.
+* The OPID itself.
+* A description of the operation as captured from the log messages.
+
+The rows are sorted by the start time of each operation.
+
+If an operation row is in the focused time span, a reverse-video
+bar will show when the operation started and finished (unless it
+extends outside the time span). As you move the focused line, the
+focused time span will be adjusted to keep the preceding and following
+five operations within the span.
+
+The preview panel at the bottom of the display will show the
+messages associated with the focused operation.
+
+The following hotkeys can be useful in this view:
+
+* :kbd:`p` -- If the log format defined sub-operations with the
+ :code:`opid/subid` property, this will toggle an overlay panel
+ that displays the sub-operation descriptions.
+
+ .. figure:: lnav-gantt-2.png
+ :align: center
+
+ Screenshot showing the same log as above after pressing
+ :kbd:`p`. The overlay panel shows a breakdown of
+ sub-operations performed while processing the main operation.
+
+* :kbd:`Shift` + :kbd:`q` -- Return to the previous view and change
+ its focused line to match the time that was focused in the gantt
+ view.
+* :kbd:`Shift` + :kbd:`a` -- After leaving the gantt view, pressing
+ these keys will return to the Gantt view while keeping the focused
+ time in sync.
+
PRETTY
^^^^^^
@@ -325,3 +416,71 @@ range of values. The panel at the bottom of the view shows the data points
themselves from the original source, the log file or the SQL query results.
You can press :kbd:`TAB` to focus on the details panel so you can scroll
around and get a closer look at the values.
+
+.. _ui_mouse:
+
+Mouse Support (v0.12.2+)
+------------------------
+
+With mouse support enabled, either through the `/ui/mouse/mode`
+configuration option or by pressing :kbd:`F2`, many of the UI
+elements will respond to mouse inputs:
+
+* clicking on the main view will move the cursor to the given
+ row and dragging will scroll the view as needed;
+* double-clicking in the main view will select the underlying
+ text and drag-selecting within a line will select the given
+ text;
+* when double-clicking text: if the mouse pointer is inside
+ a quoted string, the contents of the string will be selected;
+ if the mouse pointer is on the quote, the quote will be included
+ in the selection; if the mouse pointer is over a bracket
+ (e.g. [],{},()) where the matching bracket is on the same line,
+ the selection will span from one bracket to the other;
+* when text is selected, a menu will pop up that can be used
+ to filter based on the current text, search for it, or copy
+ it to the clipboard;
+* right-clicking the start of a log message in the main view
+ will open the parser details overlay;
+* the parser details now displays a diamond next to fields to
+ indicate whether they are shown/hidden and this can be
+ clicked to toggle the state;
+* the parser details will show a bar chart icon for fields with
+ values which, when clicked, will open either the spectrogram
+ view for the given field or open the DB query prompt with a
+ PRQL query to generate a histogram of the field values;
+* clicking in the scroll area will move the view by a page,
+ double-clicking will move the view to that area, and
+ dragging the scrollbar will move the view to the given spot;
+* clicking on the breadcrumb bar will select a crumb and
+ selecting a possibility from the popup will move to that
+ location in the view;
+* clicking on portions of the bottom status bar will trigger
+ a relevant action (e.g. clicking the line number will open
+ the command prompt with :code:`:goto <current-line>`);
+* clicking on the configuration panel tabs (i.e. Files/Filters)
+ will open the selected panel and clicking parts of the
+ display in there will perform the relevant action (e.g.
+ clicking the diamond will enable/disable the file/filter);
+* clicking in a prompt will move the cursor to the location;
+* clicking on a column in the spectrogram view will select it.
+
+.. note::
+
+ A downside of enabling mouse support is that normal text
+ selection and copy will no longer work. While lnav has
+ some support for selection in the main view, there are
+ still likely to be cases where that is insufficient.
+ In those cases, you can press :kbd:`F2` to quickly
+ switch back-and-forth. Or, some terminals have support
+ for switching while a modifier is pressed:
+
+ .. list-table::
+ :header-rows: 1
+
+ * - Key
+ - Terminal
+ * - :kbd:`Option`
+ - iTerm, Hyper
+ * - :kbd:`Fn`
+ - Terminal.app
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.
generated by cgit v1.2.3 (git 2.39.1) at 2024-06-26 18:01:44 +0000