Refactor ClpKeyValuePairStreamHandler docs.

Author: kirkrodrigues

README.md

@@ -30,27 +30,31 @@ The package is hosted with pypi (https://pypi.org/project/clp-logging/), so it
 can be installed with `pip`:
 
 `python3 -m pip install --upgrade clp-logging`
+  
+## Logging handlers
+
+### ClpKeyValuePairStreamHandler
 
-## Logging key-value pairs with `ClpKeyValuePairStreamHandler`
+⭐ *New in v0.0.14*
 
-Introduced in version 0.0.14, `ClpKeyValuePairStreamHandler` enables applications to log and
-serialize key-value pair objects directly into the CLP key-value pair IR stream format using
-Python's standard logging APIs. It operates similarly to Python's standard `logging.StreamHandler`,
-with the following differences:
-- Log events (`logging.LogRecord`) should contain the key-value pairs that a user wants to log
-  as a Python dictionary.
-  - These key-value pairs are written directly, without being formatted as a string.
-- The key-value pairs will be serialized into the CLP key-value pair IR format before writing to
-  the stream.
+This handler enables applications to write structured log events directly into CLP's key-value pair
+(kv-pair) IR stream format. The handler accepts structured log events in the form of Python
+dictionaries, where each dictionary entry must abide by the requirements detailed
+[below](#key-value-pair-requirements). The handler will also automatically include certain
+[metadata](#automatically-generated-kv-pairs), like the log event's level, with each log event.
 
-> [!NOTE]  
-> The current `ClpKeyValuePairStreamHandler` does not support `CLPLogLevelTimeout`. This feature
-> will be added in a future release.
+> [!NOTE]
+> Since this handler accepts structured log events, it doesn't support setting a
+> [Formatter][py-logging-formatter] (because the log events don't need formatting into a string).
+
+> [!WARNING]
+> `ClpKeyValuePairStreamHandler` currently doesn't support
+> [CLPLogLevelTimeout](#log-level-timeout-feature-clplogleveltimeout). This feature will be added in
+> a future release.
 
-### Key-value pairs as Python dictionary
+#### Key-value pair requirements
 
-Key-value pairs in the log event, presented as Python dictionaries, must abide by the following
-rules:
+`ClpKeyValuePairStreamHandler` requires kv-pairs abide by the following rules:
 
 - Keys must be of type `str`.
 - Values must be one of the following types:
@@ -62,29 +66,31 @@ rules:
     - must adhere to the aforementioned rules for keys and values.
     - can be empty.
 
-### Auto-generated kv-pairs vs. User-generated kv-pairs
+#### Automatically generated kv-pairs
 
-As detailed [here][clp-ffi-py-kv-pair-ir-stream], each log event contains both auto-generated and
-user-generated kv-pairs. 
+In addition to the kv-pairs explicitly logged by the application, the handler will add kv-pairs,
+like the log event's level, to each log event. We refer to the former as *user-generated* kv-pairs
+and the latter as *auto-generated* kv-pairs.
 
-In this logging handler, we differentiate auto/user-generated kv-pairs as follows:
-- **Auto-generated kv-pairs**: The log event metadata generated by the Python logging infrastructure
-  or logging handler itself, structured with the following schema:
-  - "timestamp" (`dict`):
-    - "unix_millisecs" (`int`): Unix timestamp in milliseconds since epoch.
-    - "utc_offset_secs" (`int`): The number of seconds the timezone is ahead of (positive) or
-      behind (negative) UTC.
-  - "level" (`dict`):
-    - "name" (`str`): Log level name.
-    - "num" (`int`): The numeric value associated with the log level.
-  - "source_location" (`dict`):
-    - "path" (`str`): Source file path of the logging statement.
-    - "line" (`int`): Line number of the logging statement.
-- **User-generated kv-pairs**: Key-value pairs provided by the application via the Python logging
-  API. These are passed through without modification and serialized as-is.
+> [!NOTE]
+> The kv-pair IR stream format stores auto-generated kv-pairs separately from user-generated
+> kv-pairs, so users don't need to worry about key collisions with the auto-generated keys.
 
+The handler adds the following auto-generated kv-pairs to each log event:
 
-### Example: Use `ClpKeyValuePairStreamHandler` to log Python dictionary
+| Key                 | Value type | Description                                       |
+|---------------------|------------|---------------------------------------------------|
+| `timestamp`         | `dict`     | The log event's timestamp                         |
+| - `unix_millisecs`  | `int`      | The timestamp as a Unix timestamp in milliseconds |
+| - `utc_offset_secs` | `int`      | The timestamp's UTC offset in seconds             |
+| `level`             | `dict`     | The log event's level                             |
+| - `name`            | `str`      | The level's name                                  |
+| - `num`             | `int`      | The level's numeric value                         |
+| `source_location`   | `dict`     | The source location of the logging statement      |
+| - `path`            | `str`      | The source location's path                        |
+| - `line`            | `int`      | The source location's line number                 |
+
+### Example: `ClpKeyValuePairStreamHandler`
 
 ```python
 import logging
@@ -104,16 +110,15 @@ logger.info({
 })
 ```
 
-### Read key-value pair IR streams
+### Reading kv-pair IR streams
 
 The following options are available for reading and deserializing kv-pair IR streams generated by
 this handler:
-- [clp-ffi-py][clp-ffi-py-pypi]: This library provides [Deserializer][clp-ffi-py-deserializer-doc]
-  to access a kv-pair IR stream in Python. See [this example][clp-ffi-py-deserializer-example] for
-  usage details.
-- clp-ffi-js: TODO
-  
-## Logging handlers
+
+- [clp-ffi-py][clp-ffi-py-pypi]: This library provides a [Deserializer][clp-ffi-py-deserializer-doc]
+  to access a kv-pair IR stream in Python. [This example][clp-ffi-py-deserializer-example]
+  illustrates its usage.
+- [YScope Log Viewer][2]: This UI can be used to view kv-pair IR streams.
 
 ### CLPStreamHandler
 
@@ -353,4 +358,5 @@ word][7].
 [clp-ffi-py-deserializer-doc]: https://github.com/y-scope/clp-ffi-py?tab=readme-ov-file#example-code-using-deserializer-to-read-keyvaluepairlogevents-from-an-ir-stream
 [clp-ffi-py-deserializer-example]: https://github.com/y-scope/clp-ffi-py?tab=readme-ov-file#example-code-using-deserializer-to-read-keyvaluepairlogevents-from-an-ir-stream
 [clp-ffi-py-kv-pair-ir-stream]: https://github.com/y-scope/clp-ffi-py?tab=readme-ov-file#using-key-value-pair-ir-streams
-[clp-ffi-py-pypi]: https://pypi.org/project/clp-ffi-py/
+[clp-ffi-py-pypi]: https://pypi.org/project/clp-ffi-py/
+[py-logging-formatter]: https://docs.python.org/3/library/logging.html#logging.Formatter