Add additional details about log structure

docs/cli/logs.md

@@ -28,13 +28,19 @@ The logs for a function will look
 <RCF8601 Timestamp> <function name> (<container instance>) <msg>
 ```
 
-where `msg` is the container logs, this typically contains stdout and stderr of the _contianer_.
+where `msg` is the container logs, this typically contains stdout and stderr of the _container_.  The values of `<RCF8601 Timestamp>`, `<function name>`, `<container instance>` come from the log provider (by default this is the orchestration systems: Kubernetes log API or journalctl).
 
 An example log output for `nodeinfo` from the function store is
 
 ```sh
 2019-07-21 07:57:14.437219758 +0000 UTC nodeinfo (nodeinfo-867cc95845-p9882) 2019/07/21 07:57:14 Wrote 92 Bytes - Duration: 0.121959 seconds
 ```
+Here
+
+* `<RCF8601 Timestamp>` is `2019-07-21 07:57:14.437219758 +0000 UTC`,
+* `<function name>` is `nodeinfo`,
+* `<container instance>` is `nodeinfo-867cc95845-p9882`, and
+* `<msg>` is `2019/07/21 07:57:14 Wrote 92 Bytes - Duration: 0.121959 seconds` where `2019/07/21 07:57:14` is the timestamp prefix and `Wrote 92 Bytes - Duration: 0.121959 seconds` the log message from the watchdog.
 
 You can also get logs in JSON format:
 
@@ -81,3 +87,22 @@ The log system is designed to be extended with alternative providers, this means
 Structured logs are a form of machine-readable logs that treats logs as data sets rather than text which allows logs to be more easily searched and analyzed. Typically, these will be in the form of a JSON object on a single line and will allow you to achieve a high level of granular detail.
 
 Introduced in of-watchdog v0.8.2, you can set the `prefix_logs` environment variable to `false`. This will remove the log prefix for all messages received via stdout/stderr, meaning that only the `<msg>` will be sent to the terminal.
+
+Revisiting the example from earlier, when `prefix_logs = false`, the CLI log output will be
+
+```sh
+2019-07-21 07:57:14.437219758 +0000 UTC nodeinfo (nodeinfo-867cc95845-p9882) Wrote 92 Bytes - Duration: 0.121959 seconds
+```
+Here
+
+* `<RCF8601 Timestamp>` is `2019-07-21 07:57:14.437219758 +0000 UTC`,
+* `<function name>` is `nodeinfo`,
+* `<container instance>` is `nodeinfo-867cc95845-p9882`, and
+* `<msg>` is `Wrote 92 Bytes - Duration: 0.121959 seconds` is the log message from the watchdog.
+
+The CLI allows you to hide the metadata fields, to get _just_ the log message without any metadata, deploy your function with `prefix_logs = false` and use these flags
+
+```
+$ faas-cli logs <function name> --name=false --instance=false --time-format=''
+Wrote 92 Bytes - Duration: 0.121959 seconds
+```

docs/deployment/troubleshooting.md

@@ -36,7 +36,7 @@ Next, check the events in the openfaas namespace:
 
 ```bash
 kubectl get events -n openfaas \
-  --sort-by=.metadata.creationTimestamp 
+  --sort-by=.metadata.creationTimestamp
 ```
 
 Common issues:
@@ -69,7 +69,7 @@ Next, check the events in the openfaas-fn namespace:
 
 ```bash
 kubectl get events -n openfaas-fn \
-  --sort-by=.metadata.creationTimestamp 
+  --sort-by=.metadata.creationTimestamp
 ```
 
 Common issues:
@@ -161,20 +161,28 @@ Alternatively, consider using the [Single-Sign On module from OpenFaaS PRO](http
 You will need to ensure that you are doing one of the following:
 
 * Setting `direct_functions` to false, which allows the provider to balance calls randomly between replicas of your functions.
-* Use a service mesh like Linkerd or Istio, which can do advanced traffic-management such as least-connections 
+* Use a service mesh like Linkerd or Istio, which can do advanced traffic-management such as least-connections
 
 ### I want to remove OpenFaaS from a cluster
 
 See the [Helm chart instructions](https://github.com/openfaas/faas-netes/tree/master/chart/openfaas)
 
 ### How can I use structured logs in my function
 
-By default, the logs will be in the format
+By default, the watchdog will prefix the function logs with a timestamp
 
 ```
-<RCF8601 Timestamp> <function name> (<container instance>) <msg>
+<RCF8601 Timestamp> <msg>
 ```
 
 By setting the environment variable `prefix_logs` to `false` in your function, this will only send the `<msg>` part to the terminal. This allows you to use structured logs that outputs a JSON (or equivalent) payload.
 
+Note that the `faas-cli logs` command will still include function metadata in the output
+
+```
+<RCF8601 Timestamp> <function name> (<container instance>) <msg>
+```
+
+The values of `<RCF8601 Timestamp>`, `<function name>`, `<container instance>` come from the log provider and are not part of the log message, the fields can be disabled with CLI flags.
+
 See the [Logs](https://docs.openfaas.com/cli/logs/#structured-logs) documentation for more details.