[tor-bugs] #20128 [Metrics/CollecTor]: Make CollecTor operators aware of logging (was: CollecTor log to mail-appender)

[Tor Bug Tracker & Wiki]

#20128: Make CollecTor operators aware of logging
-------------------------------+---------------------------------
 Reporter:  iwakeh             |          Owner:
     Type:  enhancement        |         Status:  new
 Priority:  Medium             |      Milestone:  CollecTor 1.1.0
Component:  Metrics/CollecTor  |        Version:
 Severity:  Normal             |     Resolution:
 Keywords:                     |  Actual Points:
Parent ID:                     |         Points:
 Reviewer:                     |        Sponsor:
-------------------------------+---------------------------------
Changes (by iwakeh):

 * milestone:   => CollecTor 1.1.0


Old description:

> Use logbacks mail-appender for mailing ERROR level mails.
> I don't want to "hide" the configuration in a wiki page, but it should
> not be part of the default log configuration.
> Where should it go?
> Commented in the default logback.xml or ... ?
>
> === Simple setup
> The following is the minimal setup that works for me, see
> [http://logback.qos.ch/manual/appenders.html#SMTPAppender logback
> documentation] for more parameters.
>
> * This appender needs to be added to logback.xml
> {{{
>   <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
>     <smtpHost>smtphost.org</smtpHost>
>     <to>the at email.somewhere</to>
>     <subject>%logger{20} - %m</subject>
>     <layout class="ch.qos.logback.classic.html.HTMLLayout"/>
>
>     <cyclicBufferTracker
> class="ch.qos.logback.core.spi.CyclicBufferTracker">
>       <!-- send immediately, if an ERROR occurs -->
>       <bufferSize>1</bufferSize>
>     </cyclicBufferTracker>
>   </appender>
> }}}
>
> * and this `<appender-ref ref="EMAIL" />` to the root-element.
> * In addition the gnu-mail jars (available in debian) have to be added to
> the classpath, i.e. `/usr/share/java/gnumail.jar:/usr/share/java/gnumail-
> providers.jar`.
>
> The logback appender only mails in case of /errors/. Anything different
> needs an implementation of `EventEvaluator` (cf.
> [http://logback.qos.ch/manual/appenders.html#TriggeringEvent logback
> documentation]).

New description:

 The logging framework configuration should be decoupled from CollecTor,
 i.e.

 * remove default logback.xml from `collector-<version>.jar`
 * add an example of logback.xml to src/main/resources
 * provide the two `logback-{classic,core}.jar`s with a release, but remove
 them from `collector-<version>.jar`
 * add more logging info to the operating guide

 The goal should be to make operators aware of the logging choices and
 their responsibilities.  Without a default logging setup operators will
 have to think about choices like

 * logging framework implementation
 * log-level settings
 * logging environment, e.g. path settings etc.

 Once an instance is configured these logging settings won't just change
 magically and thus issues like #20079 will be avoided.

--

Comment:

 An example that should be added to logback.xml:

 Use logbacks mail-appender for mailing ERROR level mails.

 === Simple setup
 The following is the minimal setup that works for me, see
 [http://logback.qos.ch/manual/appenders.html#SMTPAppender logback
 documentation] for more parameters.

 * This appender needs to be added to logback.xml
 {{{
   <appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
     <smtpHost>smtphost.org</smtpHost>
     <to>the at email.somewhere</to>
     <subject>%logger{20} - %m</subject>
     <layout class="ch.qos.logback.classic.html.HTMLLayout"/>

     <cyclicBufferTracker
 class="ch.qos.logback.core.spi.CyclicBufferTracker">
       <!-- send immediately, if an ERROR occurs -->
       <bufferSize>1</bufferSize>
     </cyclicBufferTracker>
   </appender>
 }}}

 * and this `<appender-ref ref="EMAIL" />` to the root-element.
 * In addition the gnu-mail jars (available in debian) have to be added to
 the classpath, i.e. `/usr/share/java/gnumail.jar:/usr/share/java/gnumail-
 providers.jar`.

 The logback appender only mails in case of /errors/. Anything different
 needs an implementation of `EventEvaluator` (cf.
 [http://logback.qos.ch/manual/appenders.html#TriggeringEvent logback
 documentation]).

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/20128#comment:1>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online