Output format

##Overview Converge outputs should be:

1. Easy to understand and reason about what is happening during a run
2. consumable by external tools
3. have varying levels of verbosity
4. express status via return codes
5. support live updates and overall progress
6. summarize activity at the end of a run

###Expressing output

###Examples ####Streaming output Converge can provide live updates to clients via grpc. Since tasks and checks can be run in parallel the output should be able to interleave results in a manner that supports command line tools like grep and rpc clients like a live-updating web UI:

(12/21) Check.Task: /docker_image.hyperkube: "kubernetes/hyperkube:1.4.2 not found"
(6/21)  Apply.Task: /certstap_bin: "downloading https://dl.aster.is/certstrap-linux"
(8/21)  Apply.Task: /docker_image.hyperkube: "pulling kubernetes/hyperkube:1.4.2…"
(8/21)  Apply.Task: /docker_image.hyperkube: "Using default tag: latest"
(8/21)  Apply.Task: /docker_image.hyperkube: "latest: Pulling from kubernetes/hyperkube:1.4.2"
(8/21)  Apply.Task: /docker_image.hyperkube: "952132ac251a: Downloading [=================>                                ] 17.78 MB/49.73 MB"
(8/21)  Apply.Task: /docker_image.hyperkube: "82659f8f1b76: Download complete"
(6/21)  Apply.Task: /certstap_bin: "created /usr/bin/certstrap"
(8/21)  Apply.Task: /docker_image.hyperkube: "c19118ca682d: Download complete"
(6/21)  Apply.Task: /certstap_bin: "changing /usr/bin/certstrap mode to 0755"

Fields:

1. task count/total number of tasks (for progress meters)
2. action type
3. resource name
4. resource output

Modules should have the capability to format their streaming update messages. For example, the docker pull progress rocket is noisy and not as useful when interleaved with the output of other tasks. The docker module could format the messages in a more readable format:

(8/21)  Apply.Task: /docker_image.hyperkube: "latest: Pulling from kubernetes/hyperkube:1.4.2"
(8/21)  Apply.Task: /docker_image.hyperkube: "952132ac251a: Downloading 30% complete (121 MB remaining)
(8/21)  Apply.Task: /docker_image.hyperkube: "952132ac251a: Downloading 40% complete (96 MB remaining)

Summary output, command line mode:

At the end of a run summary output can be expressed in Yaml or other output formats. Yaml will be the default for a cli run:

/directory.converge_ssl:
             Description: "Create converge ssl directory"

             Check: "/etc/converge/ssl" exists
                 Result:  "/etc/converge/ssl does not exist"
                 Status: Should Change

             Check: directory.mode 0700
                       Result: "/etc/converge/ssl does not exist"
                       Status: Should Change


             Check:
               Summary: Resource Requires Changes.

             Apply:
               Status: Apply Deltas

             Apply: Success
                  Apply.Result:
                            directory.converge.ssl_destination: <no directory> -> "/etc/converge/ssl"
                            directory.converge_ssl.mode: undefined -> 0700

              Summary:
                         2 successful changes
                         0 errors

Some output (package installs, docker pulls, file content) can be very large and is currently displayed in the summary output. Each module could be responsible for defining a concise summary of what it did and that can be shown by default in the summary. Full output might be available behind a CLI flag.

Advanced output

If all of the output could be serialized to JSON, we could give users the ability to fully customize output for use in scripts and other automation tools. For example:

• the ability to serialize output to json, yaml, and other formats. This would let users use tools like jq and jsonpath to extract the data they need.
• the ability to use templates to define the exact output desired. See kubectl --output, kubectl --template, and docker --format for examples.