some basic logging documentation

4 files changed, 46 insertions, 10 deletions

diff --git a/site/src/main/jekyll/core/logging.md b/site/src/main/jekyll/core/logging.md
index e69de29b..d8324f82 100644
--- a/site/src/main/jekyll/core/logging.md
+++ b/site/src/main/jekyll/core/logging.md
@@ -0,0 +1,43 @@
+---
+title: Kamon | Core | Documentation
+layout: default
+---
+
+Logging
+=======
+
+Kamon provides a very simple way to make sure that the trace token available when the log statement was executed is
+included in your logs, no matter if you are logging synchronously or asynchronously. Kamon provides built in support
+for logging with Logback, but extending the support to any other logging framework should be a trivial task.
+
+When using `ActorLogging` all logging events are sent to your actor system's event stream and then picked up by your
+registered listeners for actual logging. Akka captures the actor, thread and timestamp from the instant in which the
+event was generated and makes that info available when performing the actual logging. As an addition to this, Kamon
+attaches the `TraceContext` that is present when creating the log events and makes it available when the actual logging
+is performed. If you are using the loggers directly then the `TraceContext` should be already available.
+
+`TraceRecorder.currentContext` gives you access to the currently `TraceContext`, so the following expression gives you
+the trace token for the currently available context:
+
+```scala
+TraceRecorder.currentContext.map(_.token)
+```
+
+Kamon already packs a Logback converter that you can register in your `logback.xml` file and use in your logging
+patterns as show bellow:
+
+```xml
+<configuration scan="true">
+    <conversionRule conversionWord="traceToken" converterClass="kamon.trace.logging.LogbackTraceTokenConverter" />
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%date{HH:mm:ss.SSS} %-5level [%traceToken][%X{akkaSource}] %msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <root level="debug">
+        <appender-ref ref="STDOUT" />
+    </root>
+
+</configuration>
+```
diff --git a/site/src/main/jekyll/core/trace.md b/site/src/main/jekyll/core/tracing.md
index fea0f24b..bf79bd47 100644
--- a/site/src/main/jekyll/core/trace.md
+++ b/site/src/main/jekyll/core/tracing.md
@@ -88,8 +88,8 @@ has become a no brainer: each `TraceContext` created by Kamon gets a unique toke
 patterns (the first value between square brackets) and with that small but important piece of information the relation
 between each log line is clear.
 
-Just by logging the trace token you get a lot of information, refer to the logging section to learn how to log the trace
-token in your application.
+Just by logging the trace token you can get a lot of visibility and coherence in the information available on your logs,
+please  refer to the [logging](../logging/) section to learn how to include the trace token in your logs.
 
 
 Rules for `TraceContext` Propagation
diff --git a/site/src/main/jekyll/index.html b/site/src/main/jekyll/index.html
index d19e62fd..f8accbf3 100644
--- a/site/src/main/jekyll/index.html
+++ b/site/src/main/jekyll/index.html
@@ -35,7 +35,7 @@ title: Kamon - Tools for Reactive Applications Monitoring
             <li>Message processing times</li>
             <li>Time waiting in mailbox</li>
             <li>Mailbox sizes</li>
-            <li>Message flow tracing</li>
+            <li><a href="/core/tracing/">Message flow tracing</a></li>
             <li>Dispatchers health <span class="label label-info">soon</span></li>
           </ul>
       </p>
diff --git a/site/src/main/jekyll/traces/index.md b/site/src/main/jekyll/traces/index.md
deleted file mode 100644
index fe84cbdf..00000000
--- a/site/src/main/jekyll/traces/index.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: kamon | Traces | Documentation
-layout: default
----
-Coming soon
---------
-