972939 - Add preliminary documentation for structured logging

Status: RESOLVED FIXED

(Testing :: Mozbase, defect)

Description

[William Lachance (:wlach) (use needinfo!)]

As discussed in the mozbase meeting today, let's add some class-level documentation about the structured logging for mozlog, as well as some examples of how to use it.

For now it can go in a seperate section, as we're still keeping the old log stuff for backwards compatibility.

Existing documentation here:

https://github.com/mozilla/mozbase/blob/master/docs/mozlog.rst (canonical location will be testing/mozbase/docs/mozlog.rst soon)

Comment 1

[James Graham [:jgraham]]

Attachment: 972939.diff

Documentation as part of the mozbase docs.

Comment 2

[William Lachance (:wlach) (use needinfo!)]

Comment on attachment 8379020 [details] [diff] [review]
972939.diff

Review of attachment 8379020 [details] [diff] [review]:
-----------------------------------------------------------------

I think this looks good. I only really have one comment on the documentation itself. (I might have more suggestions later after actually trying to use this documentation)

I really think we need some kind of higher-level discussion in the docs about the relationship of "structured" logging to the existing logging, and when each should be used. If we want to deprecate the old mozlog functionality in favour of this, we should really just call that out so as to guide people in the right direction.

::: testing/mozbase/docs/mozlog_structured.rst
@@ +123,5 @@
> +    ``WARNING``, ``INFO``, ``DEBUG``).
> +
> +  ``message``
> +    Text of the log message.
> +

A few end-to-end examples of what a log message looks like might be helpful here.

Comment 3

[James Graham [:jgraham]]

Attachment: 972939-1.diff

Same patch with updated commit message.

Comment 4

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/integration/mozilla-inbound/rev/b9398216b902

Comment 5

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

https://hg.mozilla.org/mozilla-central/rev/b9398216b902