help text for juju debug-log needs improving

[Peter Matulis]

e.g.:

Usage: juju debug-log [options]

Summary:
Displays log messages for a model.

Options:

-T, --no-tail (= false)
    Stop after returning existing log messages
--exclude-module (= )
    Do not show log messages for these logging modules
-i, --include (= )
    Only show log messages for these entities
--include-module (= )
    Only show log messages for these logging modules
-l, --level (= "")
    Log level to show, one of [TRACE, DEBUG, INFO, WARNING, ERROR]
--limit (= 0)
    Exit once this many lines are shown
-m, --model (= "")
    Model to operate in
-n, --lines (= 10)
    Show a maximum of this many lines after filtering
--replay (= false)
    Show all lines after filtering
-x, --exclude (= )
    Do not show log messages for these entities

Details:
This command accesses all logged Juju activity on a per-model basis. By default, the model is the current model.
A log line is written in this format:
<entity> <timestamp> <log-level> <module>:<line-no> <message>
The "entity" is the source of the message: a machine or unit. Both are obtained in the output to `juju status`.
The '--include' and '--exclude' options filter by entity. A unit entity is identified by prefixing 'unit-' to its corresponding unit name and replacing the slash with a dash. A machine entity is identified by prefixing 'machine-' to its corresponding machine id.
The '--include-module' and '--exclude-module' options filter by (dotted) logging module name, which can be truncated.
A combination of machine and unit filtering uses a logical OR whereas a combination of module and machine/unit filtering uses a logical AND.
Log levels are cumulative; each lower level (more verbose) contains the preceding higher level (less verbose).

Examples:

Exclude all machine 0 messages; show a maximum of 100 lines; and continue to append filtered messages:

    juju debug-log --exclude machine-0 --lines 100

Include only unit mysql/0 messages; show a maximum of 50 lines; and then exit:

    juju debug-log -T --include unit-mysql-0 --lines 50

Show all messages from unit apache2/3 or machine 1 and then exit:

    juju debug-log -T --replay --include unit-apache2-3 --include machine-1

Include all juju.worker.uniter logging module messages that are also unit wordpress/0 messages and continue to append filtered messages:

    juju debug-log --replay --include-module juju.worker.uniter --include unit-wordpress-0

To see all WARNING and ERROR messages:

    juju debug-log --replay --level WARNING

See also: status

[Tim Penhey (thumper)]

Someone should fix debug-log so it takes machine ids and unit ids, not stringified tags.

[Tim Penhey (thumper)]

Also the meaning of --replay is to show all matching log lines from the earliest that the controller has.

[Tim Penhey (thumper)]

-n, --lines (= 10)
    Show a maximum of this many lines after filtering

This is wrong too...

this specifies how many matching lines to go back from now to start outputing before continuing tailing.

So, if you go debug-log --lines 100

Means that it will try to step back 100 lines from now and output those and then tail.

If you have specified some form of filter, it will go back 100 matching lines.

[Tim Penhey (thumper)]

The details blob is too hard to read without blank lines between the paragraphs. It is a wall of text.

[Peter Matulis (petermatulis)]

Possible adjustments

-n, --lines (= 10)
    Show a maximum of this many lines after filtering

-n, --lines (= 10)
    Show this many of the most recent (possibly filtered) lines, and continue to append

=======

--limit (= 0)
    Exit once this many lines are shown

--limit (= 0)
    Exit once this many of the most recent (possibly filtered) lines are shown

=======

--replay (= false)
    Show all lines after filtering

--replay (= false)
    Show the entire (possibly filtered) log and continue to append

[Reed O'Brien (reedobrien)]

Is this ready to go? The comments look like the conversation fell off. For now I will use what is in the description.

[Reed O'Brien (reedobrien)]

Decided to use the updated text in comment #5:

Output:

Usage: juju debug-log [options]

Summary:
Displays log messages for a model.

Options:
-T, --no-tail (= false)
    Stop after returning existing log messages
--exclude-module (= )
    Do not show log messages for these logging modules
-i, --include (= )
    Only show log messages for these entities
--include-module (= )
    Only show log messages for these logging modules
-l, --level (= "")
    Log level to show, one of [TRACE, DEBUG, INFO, WARNING, ERROR]
--limit (= 0)
    Exit once this many of the most recent (possibly filtered) lines are shown
-m, --model (= "")
    Model to operate in
-n, --lines (= 10)
    Show this many of the most recent (possibly filtered) lines, and continue to append
--replay (= false)
    Show the entire (possibly filtered) log and continue to append
-x, --exclude (= )
    Do not show log messages for these entities

Details:
This command accesses all logged Juju activity on a per-model basis. By
default, the model is the current model.
A log line is written in this format:
<entity> <timestamp> <log-level> <module>:<line-no> <message>
The "entity" is the source of the message: a machine or unit. Both are
obtained in the output to `juju status`.
The '--include' and '--exclude' options filter by entity. A unit entity is
identified by prefixing 'unit-' to its corresponding unit name and
replacing the slash with a dash. A machine entity is identified by
prefixing 'machine-' to its corresponding machine id.
The '--include-module' and '--exclude-module' options filter by (dotted)
logging module name, which can be truncated.
A combination of machine and unit filtering uses a logical OR whereas a
combination of module and machine/unit filtering uses a logical AND.
Log levels are cumulative; each lower level (more verbose) contains the
preceding higher level (less verbose).

Examples:
Exclude all machine 0 messages; show a maximum of 100 lines; and continue
to append filtered messages:

    juju debug-log --exclude machine-0 --lines 100

Include only unit mysql/0 messages; show a maximum of 50 lines; and then
exit:

    juju debug-log -T --include unit-mysql-0 --lines 50

Show all messages from unit apache2/3 or machine 1 and then exit:

    juju debug-log -T --replay --include unit-apache2-3 --include machine-1

Include all juju.worker.uniter logging module messages that are also unit
wordpress/0 messages and continue to append filtered messages:

    juju debug-log --replay --include-module juju.worker.uniter --include \
        unit-wordpress-0

To see all WARNING and ERROR messages:

    juju debug-log --replay --level WARNING

See also:
    status

[Peter Matulis (petermatulis)]

Thank you. Comment #5 is best IMO.