Document the different debug levels

[stuclem]

From @stuclem on May 30, 2016 15:14

Per vmware/vic#709.

Copied from original issue: vmware/vic#852

[stuclem]

vmware/vic#709 is in GA release.

[stuclem]

When implemented, will require an update to the existing section on --debug in the topic on vic-machine create options, and a section in Admin about how to access and understand the information.

[stuclem]

vmware/vic#709 is implemented in PRs vmware/vic#1216 and vmware/vic#1217.

[stuclem]

According to Faiyaz, vmware/vic#1216 is internal.

[stuclem]

According to @hickeng in https://communities.vmware.com/message/2626719#2626719, setting debug to 3 suppresses the restart of failed components. We need to find out and document the exact effect of setting debug to 1, 2, 3 ... n. Currently we just talk about setting debug to a value >1.

[stuclem]

Not required for 0.7, so moving back to backlog.

[stuclem]

In vmware/vic#3081 (comment) @hickeng says that debug >2 automatically enables SSH.

@hickeng are these debug levels spec'd anywhere?

[stuclem]

Added more info to https://github.com/stuclem/vic/blob/master/doc/user_doc/vic_installation/vch_installer_options.md#--debug: "For example, setting --debug to 2 or greater automatically enables SSH access to the VCH endpoint VM. Setting --debug to 3 suppresses the restart of failed components." I do feel that this is very incomplete, though. I would really like to obtain a proper list of what each logging level does.

@hickeng do you have more info about what each logging level does? I have a snippet for 2 and 3, but what about 4, 5, ... n? How high can n be?

[stuclem]

Nice to have for 1.1, but might not make the cut.

[stuclem]

Still no info about this. Moving out of 1.1.

[hickeng]

@stuclem Not spec'd as such - I've opened vmware/vic#4575 to do a better job of this. But the basics are:

1: extra verbosity, no changes to behaviour
2: changes to behaviour - exposes servers on more interfaces, launches pprof in containerVMs
3: disable recovery logic, log sensitive data - disables component restart in appliance, and containerVM shutdown. Logs environment and details for user application, and collects application output in log bundle.

[stuclem]

Great, thanks @hickeng!

[stuclem]

Added the info from the comment above to the description of the vic-machine create --debug option.

Change is in stuclem@3ab8c2b. @hickeng is this OK? Thanks!

[stuclem]

Changes merged in #158, but leaving this open for final verification by @hickeng.

[hickeng]

@stuclem We're going to vet the code where the debug levels are used to confirm current behaviour - what I described was original intent but unverified.
There's an issue open (vmware/vic#4575) for a more structured and enforced approach.

I presume you just need current behaviour for this - what level of detail?

[stuclem]

@hickeng yes, we need the behaviour as it is in 1.1. I don't think that we need masses of detail - just enough to let people know why they might need or want to set a level higher than 1, and what impact that will have on their setup. Thanks!

[stuclem]

This change is merged, but leaving this issue open pending the code vetting by @hickeng.

[stuclem]

To be verified in 1.2.

[stuclem]

Given @chengwang86 's comments in #532, I think that it's safe to finally close this one.