reference/slf4j-reference/README.md

   1 # README - slf4j-reference
   2
   3 This project gives an example of ONAP-compliant logging using SLF4J logging.
   4
   5 ## Adapter
   6
   7 In ```org.onap.logging.ref.slf4j.common```, there are TWO classes:
   8 1. ```org.onap.logging.ref.slf4j.common.ONAPLogConstants```, providing declarations of standard ONAP Markers, MDCs and HTTP headers.
   9 2. ```org.onap.logging.ref.slf4j.common.ONAPLogAdapter```, providing a lightweight, compliant implementation of the ONAP logging spec.
  10
  11 The adapter provides:
  12 1. A loosely-coupled SLF4j logging wrapper:
  13  * To be used for logging ONAP ```entry```, ```exit``` and ```invoke``` behavior.
  14  * Devolving all *application* logging to the component, via the regular SLF4J ```Logger``` facade.
  15 2. Customization options:
  16  * *Cheap*, by way of bean properties. This is suited to most Use Cases.
  17  * *Sophisticated*:
  18     * By OPTIONALLY implementing one of a number of adapters:
  19       * ```RequestAdapter``` to read incoming headers.
  20       * ```ServiceDescriptor``` for reporting attributes of the current service.
  21       * ```ResponseDescriptor``` for reporting outcomes.
  22       * ```RequestBuilder``` for setting southbound request headers.
  23     * By OPTIONALLY overriding methods like ```ONAPLogAdapter#setMDCs(RequestAdapter)```.
  24
  25 Note that:
  26 * The adapter implementation uses static inner classes in order to fit in a single source file. This was an objective.
  27
  28 ## WAR
  29
  30 Building produces a simple (spring-boot](https://projects.spring.io/spring-boot/) example WAR, which can be launched from this directory with:
  31
  32 ```bash
  33 $ java -war target/*war
  34 ```
  35
  36 The WAR publishes four web services:
  37 1. ```services/alpha```
  38 2. ```services/beta```
  39 3. ```services/gamma```
  40 4. ```services/delta```
  41
  42 ... each of which can invoke the others.
  43
  44 The purpose of this WAR is to demonstrate minimalist ONAP-compliant logging for web components, but a secondary purpose is to demonstrate that the call graph can be generated for a (mostly) representative set of interacting REST services.
  45
  46 ## Tests
  47
  48 Tests for:
  49 1. Code in the (potentially) reusable ``common`` package.
  50 2. Validating that emitted logs can be used to generate an unambiguous call graph.