Logging article update, log4j2

[ThomDietrich]

In response to the merge of karaf 4.1.2 we should update the logging article, in general and with log4j2 specific notes. It would also be great to include examples for add-on specific logging and the possibility to add new appenders.

• http://docs.openhab.org/administration/logging.html
• Upgrading to Karaf 4.1.2 openhab-distro#484
• https://community.openhab.org/t/taming-openhab-2-logging/13976

@AngelosF @bgilmer77 volunteers? :)

[AngelosF]

Sure!
I started playing around already with log4j2 :)
https://community.openhab.org/t/log4j2-sample-config/33284

[bgilmer77]

I will take the admin page.

[AngelosF]

I will review and add content later then. Go ahead @bgilmer77 !

[bgilmer77]

@AngelosF it might be better if you go ahead and then I contribute later. I won't be able to get to it for a couple of days.

[ThomDietrich]

@bgilmer77 I've invited you to become a contributor for the openHAB project. That's needed to assign you to this and other issues.

[bgilmer77]

@ThomDietrich Done.

[AngelosF]

@ThomDietrich @bgilmer77
should we prepare the PR against http://docs.openhab.org/administration/logging.html and wait till OH2.2 Stable will be released or push the changes now?

Most people are still on log4j1 since they are running versions lower than OH2.2 Snapshot 1009 that included the Karaf 4.1.2 which brings along log4j2.

I will start typing up a PR for this but we could either:
a) wait for the log4j2 to be widely adopted via the 2.2.0 Stable
or
b) publish a new section in logging.html with info dedicated to log4j2

wdyt?

[kaikreuzer]

@ThomDietrich I guess we are at the point where we really should think about the docu split into different versions - did you already spend any further thoughts on this? (btw, thanks for taking care about docs update regarding logging; this is again something that I didn't spend enough thoughts on when doing the Karaf upgrade...)

[bgilmer77]

@kaikreuzer, is the idea of a document split that there is one version for 1.x, and another version for 2.x? Or do you mean to split the documentation some other way?

[AngelosF]

This is a good example of a docs split:

https://github.com/influxdata/docs.influxdata.com/tree/master/content/influxdb

i.e.:
Docs v1.1 : https://docs.influxdata.com/influxdb/v1.1/
Docs v1.3: https://docs.influxdata.com/influxdb/v1.3/

Maybe we should group the docs in the same way.

I also like the http://docs.grafana.org/ for the right hand menu (with "edit this page" and other nice links)

[bgilmer77]

@AngelosF - as you can tell, I was working through my email in reverse chronological order ;-).

Interestingly, I was just thinking about the steps to start on the logging section, and it first occurred to me that, since I am running Raspbian Jessie on the apt stable main branch, I would need to pull down the snapshot instead. No problem - create a Ubuntu VM and do it. But as you point out, most people will not be using 4j2 until it goes to the stable branch, so this could be pretty confusing.

In fact, @kaikreuzer , it occurred to me that as OH grows, perhaps it would be good to include a short statement in any significant announcements such as the one regarding the logging update that says something like, "This functionality is now available in openHab 2.2, Snapshot 1009." "It will be part of the next Stable release which should be available in X weeks/months/whatever." Or words to that effect.

Back to @AngelosF 's point, my first thought would be to suggest one document on logging, with some sort of tag which indicates that a particular section is specific to 4j1, and another tag for 4j2. This would keep people from having to bounce around in the documentation. But a disadvantage of this is that 4j1 is forever enshrined in the logging documentation page.

Another possibility is to say at the top, "THIS PAGE APPLIES TO J42. A LOGGING PAGE FOR J41 MAY BE FOUND HERE." "You can determine your logging version by [insert instructions on determining whether you are running j41 or j42 here]." Then we archive the current page with a link to it from the new page, and publish only the new page in the main documentation.

As I think this through, I like the second option best. Yes, initially 95% of the readers will be clicking the link to the j41 document, but that will change over time. Of course, it will create support chatter with posts from people who did not read the initial part at the top about going to the older documentation, but leaving the old stuff in forever seems like a mistake.

A third option would be to tag the sections 4j1 or 4j2 where there are differences as in my first suggestion, and then go back and implement the second option of a separate document at a later time. The tags would (theoretically) make this a quick job. My two cents.

[kaikreuzer]

@bgilmer77 Please wait for @ThomDietrich to comment, we had this all already discussed in detail.
The idea is simply to have a documentation per version. After all, that was the main reason to move from a wiki to a versioned repo - it would not make sense to mix all infos for the different releases on the master branch of the documentation.

[bgilmer77]

I understand. Yes, using the power of a versioned repo makes sense.

[kaikreuzer]

Just a word of warning - the Karaf guys just updated their docs to also describe log4j2 configuration and they seem to have decided to go for XML instead of property file format.

In the light of openhab/openhab-distro#516, XML might also be for us the better option - so I would suggest to not put too much effort in the documentation yet, until openhab/openhab-distro#516 is solved.

[AngelosF]

Isn't JSON prettier? :)
https://logging.apache.org/log4j/2.0/manual/configuration.html#JSON

I was thinking to try both alternatives (xml and json) and try to use json.

Either way, I wait for your updates. XML syntax for the config file is fine! (definitely better than the old style properties config)

[kaikreuzer]

Isn't JSON prettier? :)

Look at it, it is all red!
I think if we go with what Karaf uses, it might cause the least confusion. If there is some good reason to use JSON instead, I'm also open for it. But one argument for me against it is that it does not support comments, which is pretty bad for configuration files...

[AngelosF]

Ok, I am a Panathinaikos supporter, so green is my color (closer to XML) !

Standing by for openhab/openhab-distro#516 till docs update

We also need @ThomDietrich 's input with regards to the docs split :)

[ThomDietrich]

Hey guys!
Sorry still on vacation, the attention span is a bit short atm 😄

• XML over JSON for me because JSON was never designed to be a human editable format. E.g. with it's no-comments property. For an example what that motivates can be seen here 😅.

• Versioning is still an important task on my TODO list. Our mistake back then was to discuss this topic in a non-public channel. I'll open an issue ticket for the topic with all details here soon. I think this is something that may take more than a few days to finish. Hence:

• The log4j2 article is in conflict with the old content. I'd suggest to put overhaul the complete article and address log4j2 while always hinting differences with log4j. These paragraphs can then be easily deleted later. @AngelosF and @bgilmer77 would that work for you?

I hope I got everything. What do you think?

[AngelosF]

The log4j2 article is in conflict with the old content. I'd suggest to put overhaul the complete article and address log4j2 while always hinting differences with log4j. These paragraphs can then be easily deleted later.

I am not sure if I got it right... (it must be the summer time, beaches and beer) 🌞

I think that I agree, but let's clarify...

Should we go ahead and type up a completely new docs entry focusing on log4j2 and add some remarks whenever we have differences for the log4j1 content?

That would not be easy since the changes are mostly in the configuration section and that's not easy to cover with 2 sample configs (people will be confused).

I propose the following approach:

• Forget about log4j1 and focus on the future only (log4j2)
• Go ahead and significantly revamp/redo/restructure the existing docs entry, switching everything to log4j2 related content.
• Drop all log4j1 related content from http://docs.openhab.org/administration/logging.html but leave a note about "migration" from log4j1 to log4j2.
• Cover XML config syntax

Reasons:
i) openHAB 2.2 Stable should be coming soon, so log4j2 will be widely adopted. People should find a nice documentation on log4j2 online.
ii) Whoever wants to customize their logging configs based upon log4j1 (for <OH2.1) can still use the forum
iii) Don't wait till the docs versioning split is ready, since this will take sometime.
iv) Don't wait for openhab/openhab-distro#516

If we are ok with this approach, I can start typing up a first draft of the new logging docs entry and then we can all revise it.

[ThomDietrich]

You are making a good point. Let's do that ;)

Prost 🍻

[bgilmer77]

This seems like a good approach. I will wait until @AngelosF has posted the first draft and then will comment, unless @AngelosF, there is some logical way to divide and conquer the work. I expect not. Usually it is best if the first draft is written by one person so it all has the same construction. In any case, I am here if you need me to do anything.

[AngelosF]

It has been almost impossible for me to find 1-2 hours of free time to sit down and type up the first draft of the docs article... :(

I will try during the w/end to see if I can progress this one.

[bgilmer77]

@AngelosF, no problem - I am standing by. I have put together a development system running the snapshot so that I can compare the two systems running the different loggers.

[AngelosF]

Hey @bgilmer77 !

Finally, I created a PR to update this docs entry :)

Check it please to see if we can further improve it: #814

[bgilmer77]

@AngelosF I already commented on your PR, but it looks very good. Thank you.