diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/source/ui.rst | 179 |
1 files changed, 169 insertions, 10 deletions
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 |