summaryrefslogtreecommitdiffstats
path: root/docs/source/config.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/source/config.rst155
1 files changed, 113 insertions, 42 deletions
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