//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

=== Example: Logging with Logback

It is possible to have the Jetty Server logging configured so that Logback controls the output of logging events produced by Jetty.
This is accomplished by configuring Jetty for logging to `Logback`, which uses http://slf4j.org/manual.html[Slf4j] and the http://logback.qos.ch/[Logback Implementation for Slf4j].

A convenient replacement `logging` module has been created to bootstrap the `${jetty.base}` directory for logging with logback.

[source, screen, subs="{sub-order}"]
....
[mybase]$ mkdir modules
[mybase]$ cd modules

[modules]$ curl -O https://raw.githubusercontent.com/jetty-project/logging-modules/master/logback/logging.mod
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   742  100   742    0     0   2196      0 --:--:-- --:--:-- --:--:--  2201
[modules]$ cd ..

[mybase]$ java -jar /opt/jetty-dist/start.jar --add-to-start=logging
INFO: logging         initialised in ${jetty.base}/start.ini (appended)
MKDIR: ${jetty.base}/logs
DOWNLOAD: https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.6.6/slf4j-api-1.6.6.jar to lib/logging/slf4j-api-1.6.6.jar
DOWNLOAD: https://repo1.maven.org/maven2/ch/qos/logback/logback-core/1.0.7/logback-core-1.0.7.jar to lib/logging/logback-core-1.0.7.jar
DOWNLOAD: https://repo1.maven.org/maven2/ch/qos/logback/logback-classic/1.0.7/logback-classic-1.0.7.jar to lib/logging/logback-classic-1.0.7.jar
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master/logback/logback.xml to resources/logback.xml
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master/logback/jetty-logging.properties to resources/jetty-logging.properties

[mybase]$ java -jar /opt/jetty-dist/start.jar
....

The replacement `logging.mod` performs a number of tasks.

.  `mybase` is a `${jetty.base}` directory.
.  The jetty-distribution is unpacked (and untouched) into `/opt/jetty-dist/` and becomes the `${jetty.home}` directory for this demonstration.
.  The `curl` command downloads the replacement `logging.mod` and puts it into the `${jetty.base}/modules/` directory for use by `mybase` only.
.  The `start.jar --add-to-start=logging` command performs a number of steps to make the logging module available to the `${jetty.base}` configuration.
..  The `--module=logging` command is added to the `${jetty.base}/start.ini` configuration.
..  Required `${jetty.base}` directories are created: `${jetty.base}/logs` and `${jetty.base}/resources`.
..  Required libraries are downloaded (if not present already) to the `${jetty.base}/lib/logging/` directory: slf4j-api, logback-core, and logback-classic.
..  Required configuration files are downloaded (if not present already) to the `${jetty.base}/lib/resources/` directory.: `jetty-logging.properties`, and `logback.xml`.

At this point the Jetty `mybase` is configured so that the Jetty server itself will log using Logback, using the Logback configuration found in `mybase/resources/logback.xml`

The server classpath can be verified by using the `start.jar --list-config` command.

In essence, Jetty is now configured to emit its own logging events to slf4j, and slf4j itself is using the static log binder found in logback-classic.jar, making all Jetty + Slf4j + Logback events emitted by the Jetty server go to Logback for routing (to console, file, syslog, etc...).
