[docs] breakpoints

Author: tstack

docs/source/sqltab.rst

@@ -11,6 +11,7 @@ the following tables/views:
 * `lnav_events`_
 * `lnav_file`_
 * `lnav_file_metadata`_
+* `lnav_log_breakpoints`_
 * `lnav_user_notifications`_
 * `lnav_views`_
 * `lnav_views_echo`_
@@ -147,6 +148,40 @@ loaded file.  Currently,
 :mimetype: The MIME type of the metadata.
 :content: The metadata itself.
 
+
+.. _table_lnav_log_breakpoints:
+
+lnav_log_breakpoints
+--------------------
+
+The :code:`lnav_log_breakpoints` table allows you to view and manage
+breakpoints set on log messages.  Breakpoints mark log messages that
+share a particular source file location or message schema, making it
+easy to navigate between related log lines using the :kbd:`F7` and
+:kbd:`F8` keys.
+
+You can :code:`SELECT`, :code:`INSERT`, :code:`UPDATE`, and
+:code:`DELETE` breakpoints through this table.  The columns in the
+table are as follows:
+
+:schema_id: The schema identifier for the breakpoint.  This value
+  matches the :code:`log_msg_schema` column in the :code:`all_logs`
+  table.
+:description: A human-readable description of the breakpoint
+  (e.g. :code:`format_name:file.cc:42`).
+:type: The source of the schema ID, either :code:`src_location` or
+  :code:`message_schema`.
+:enabled: Indicates whether the breakpoint is active (1 or 0).
+
+.. code-block:: custsqlite
+
+    ;SELECT * FROM lnav_log_breakpoints
+
+    ;UPDATE lnav_log_breakpoints SET enabled = 0 WHERE description LIKE '%main.cc%'
+
+    ;DELETE FROM lnav_log_breakpoints WHERE description LIKE '%test%'
+
+
 .. _table_lnav_user_notifications:
 
 lnav_user_notifications

docs/source/usage.rst

@@ -300,6 +300,43 @@ Log level
 To hide messages below a certain log level, you can use the
 :ref:`:set-min-log-level<set_min_log_level>` command.
 
+
+Log-oriented Debugging
+----------------------
+
+Breakpoints
+^^^^^^^^^^^
+
+Breakpoints let you mark log messages that originate from a particular
+source file location (e.g. :code:`main.cc:42`) or that share a common
+message schema.  Log messages that have a source location and match a
+breakpoint will be highlighted with a red circle, making it easy to spot
+related messages as you scroll through logs.
+
+To toggle a breakpoint on the focused log message, press :kbd:`Ctrl` +
+:kbd:`B` or use the :ref:`:breakpoint<breakpoint>` command.
+You can also set breakpoints explicitly with the
+:ref:`:breakpoint<breakpoint>` command, specifying a
+:code:`[format:]file:line` location.
+
+Once breakpoints are set, you can jump between matching log messages
+using the :kbd:`F7` and :kbd:`F8` keys to move to the previous and next
+breakpoint hit, respectively.
+
+Breakpoints can be disabled without deleting them using the
+:ref:`:toggle-breakpoint<toggle_breakpoint>` command.
+The :ref:`lnav_log_breakpoints<table_lnav_log_breakpoints>`
+SQL table, which allows you to query, insert, update, and delete breakpoints.
+For example, to disable all breakpoints matching a file:
+
+.. code-block:: custsqlite
+
+    ;UPDATE lnav_log_breakpoints SET enabled = 0 WHERE description LIKE '%main.cc%'
+
+Breakpoints are saved as part of the session, so they will be restored
+the next time you open the same files.
+
+
 .. _search_tables:
 
 Search Tables