First test on Simantics documentation using gitbook

[simantics/platform.git] / docs / Developer / Utilities / Logging.md

diff --git a/docs/Developer/Utilities/Logging.md b/docs/Developer/Utilities/Logging.md
new file mode 100644 (file)
index 0000000..77fe5d4
--- /dev/null
+++ b/docs/Developer/Utilities/Logging.md
@@ -0,0 +1,67 @@
+For uniform logging in Simantics Platform [ The Simple Logging Facade for Java](http://www.slf4j.org/) (`org.slf4j.api`) and [Logback Project](http://logback.qos.ch/) (`ch.qos.logback.classic`) is included in Simantics SDK. To use the SLF4J logging API just include the following bundle in your own plugin's `MANIFEST.MF` dependencies:\r
+\r
+    Require-Bundle: ..,\r
+    org.slf4j.api\r
+\r
+An example usage of logging inside your own java code is presented below:\r
+\r
+~~~\r
+ 1: import org.slf4j.Logger;\r
+ 2: import org.slf4j.LoggerFactory;\r
+ 3:\r
+ 4: public class Wombat {\r
+ 5:  \r
+ 6:   private static final Logger LOGGER = LoggerFactory.getLogger(Wombat.class);\r
+ 7:   private Integer t;\r
+ 8:   private Integer oldT;\r
+ 9:\r
+10:   public void setTemperature(Integer temperature) {\r
+11:    \r
+12:     oldT = t;        \r
+13:     t = temperature;\r
+14:\r
+15:     LOGGER.debug("Temperature set to {}. Old temperature was {}.", t, oldT);\r
+16:\r
+17:     if(temperature.intValue() > 50) {\r
+18:       LOGGER.info("Temperature has risen above 50 degrees.");\r
+19:     }\r
+20:   }\r
+21: }\r
+~~~\r
+\r
+The SLF4J Manual can be found here: http://www.slf4j.org/manual.html\r
+\r
+## Configuring Logback\r
+\r
+By default bundle `org.simantics.logback.configuration` contains the `logback.xml` configuration file in which the logging format and different appenders are defined. By default it looks like this:\r
+\r
+~~~\r
+<?xml version="1.0" encoding="UTF-8"?>\r
+<configuration>\r
+\r
+  <appender name="console" class="ch.qos.logback.core.ConsoleAppender">\r
+    <!-- encoders are assigned the type ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->\r
+    <encoder>\r
+      <pattern>%-5p [%d] %c: %m%n%rEx</pattern>\r
+    </encoder>\r
+  </appender>\r
+\r
+  <appender name="async-console" class="ch.qos.logback.classic.AsyncAppender">\r
+    <appender-ref ref="console" />\r
+  </appender>\r
+\r
+  <root level="debug">\r
+    <appender-ref ref="async-console" />\r
+  </root>\r
+</configuration>\r
+~~~\r
+\r
+This configuration creates a single ''asynchronous'' `ConsoleAppender` which prints all the logging to `System.out` by. An example output would look like:\r
+\r
+    INFO  [2016-09-23 15:56:25,498] org.simantics.workbench.internal.SimanticsWorkbenchAdvisor: startPlatform finished\r
+\r
+It is possible to override this default configuration be giving a VM-argument for the application in format:\r
+\r
+    -Dlogback.configurationFile="C:\logbacs\logback.xml"\r
+\r
+For detailed information see [Logback manual](http://logback.qos.ch/manual/).\r