diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/source/config.rst | 155 |
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 |