doc: Update logging and debug docs based on review

Apply further changes to the debug and logging documents based on review
feedback.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

Author: James O. D. Hunt

README.md

@@ -81,8 +81,8 @@ $ cc-runtime cc-env
 
 ## Logging
 
-The runtime provides `--log=` and `--log-format=` options. However, it can
-also be configured to log to the system log (syslog or `journald`) such that
+The runtime provides `--log=` and `--log-format=` options. However, you can
+also configure it to log to the system log (syslog or `journald`) such that
 all log data is sent to both the specified logfile and the system log. The
 latter is useful as it is independent of the lifecycle of each container.
 
@@ -104,23 +104,26 @@ To view proxy log output:
 $ sudo journalctl -t cc-proxy
 ```
 
-Note that the proxy log entries also include output from the agent (`cc-agent`) and the
+Note:
+
+The proxy log entries also include output from the agent (`cc-agent`) and the
 hypervisor (which includes the guest kernel boot-time messages).
 
 ## Debugging
 
-The runtime, the shim (`cc-shim`), the proxy (`cc-proxy`) and the hypervisor all have separate `enable_debug=` debug
+The runtime, the shim (`cc-shim`), the proxy (`cc-proxy`),
+and the hypervisor all have separate `enable_debug=` debug
 options in the [configuration file](#Configuration). By default, all these
-debug options are disabled. Look at the comments in the installed
+debug options are disabled. See the comments in the installed
 configuration file for further details.
 
-If you wish to enable debug for all components, assuming a standard configuration file path, run:
+If you want to enable debug for all components, assuming a standard configuration file path, run:
 
 ```bash
 $ sudo sed -i -e 's/^#\(enable_debug\).*=.*$/\1 = true/g' /usr/share/defaults/clear-containers/configuration.toml
 ```
 
-For further details, see the [agent debug document](docs/debug-agent.md) and the [kernel debug document](docs/debug-kernel.md).
+See the [agent debug document](docs/debug-agent.md) and the [kernel debug document](docs/debug-kernel.md) for further details.
 
 ## Limitations
 

docs/debug-agent.md

@@ -4,19 +4,25 @@ Clear Containers runtime launch a special virtual machine when a new pod is
 created. This VM uses a VM-agent to spawn processes on behalf of the
 pod/container(s) running inside the VM.
 
-From Clear Containers 3.0-beta release a new agent (`cc-agent`) is used,
-[Clear Containers Agent](https://github.com/clearcontainers/agent).
+The Clear Containers 3.0-beta release uses a new agent (`cc-agent`),
+https://github.com/clearcontainers/agent.
 
-The Clear Containers agent relies heavily on [`libcontainer`](https://github.com/opencontainers/runc/tree/master/libcontainer) used by [`runc`](https://github.com/opencontainers/runc/) (standard program when running containers on bare metal).
+The Clear Containers agent relies heavily on [`libcontainer`](https://github.com/opencontainers/runc/tree/master/libcontainer)
+used by [`runc`](https://github.com/opencontainers/runc/), which is the
+standard program when running containers on bare metal.
 
 To provide a debug log of any agent activity on a guest, the Clear Containers
-agent sends logs through a QEMU serial console that are collected by [cc-proxy](https://github.com/clearcontainers/proxy)
-and shown in its logs. By default, the Clear Containers agent logs are not collected by 
-`cc-proxy` but can be enabled by enabling the proxy debug option.
+agent sends log data through a QEMU serial console, which is collected by
+[cc-proxy](https://github.com/clearcontainers/proxy) and shown in the proxy's
+logs.
+
+By default, the Clear Containers agent logs are not collected by `cc-proxy`
+but can be enabled by enabling the proxy debug option:
 
 1. Enable proxy debug
 
-   Set the `enable_debug=` option in the `[proxy.cc]` section to `true` (assumes a standard configuration file path):
+   Set the `enable_debug=` option in the `[proxy.cc]` section to `true`, which
+   assumes a standard configuration file path:
 
    ```
    $ sudo awk '{if (/^\[proxy\.cc\]/) {got=1}; if (got == 1 && /^#enable_debug/) {print "enable_debug = true"; got=0; next; } else {print}}' /usr/share/defaults/clear-containers/configuration.toml
@@ -30,9 +36,9 @@ and shown in its logs. By default, the Clear Containers agent logs are not colle
 
 1. Filter the agent debug logs from the `cc-proxy` logs
 
-   The `cc-proxy` logs show the sources of its collated information. To only see
-   the agent debug logs, filter `cc-proxy` logs by the QEMU serial console (the
-   agent logs were sent through it). The QEMU serial console is represented by
+   The `cc-proxy` logs show the sources of its collated information. To only
+   see the agent debug logs, filter `cc-proxy` logs by the QEMU serial console
+   that sent the agent logs.  The QEMU serial console is represented by
    `source=qemu`.
 
    ```

docs/debug-kernel.md

@@ -12,7 +12,8 @@ to enable kernel boot logs using the configuration file.
 
 1. Enable kernel boot messages
 
-   Set the `enable_debug=` option in the `[proxy.cc]` section to `true` (assumes a standard configuration file path):
+   Set the `enable_debug=` option in the `[proxy.cc]` section to `true`, which
+   assumes a standard configuration file path:
 
    ```
    $ sudo awk '{if (/^\[proxy\.cc\]/) {got=1}; if (got == 1 && /^#enable_debug/) {print "enable_debug = true"; got=0; next; } else {print}}' /usr/share/defaults/clear-containers/configuration.toml