This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit e8937d93a002f3e21ca07e58a616f4734e338999
Author: Benoit Tellier <btell...@linagora.com>
AuthorDate: Fri Jul 10 13:38:11 2020 +0700
JAMES-3302 Document logging for the Distributed Server
---
docs/modules/servers/nav.adoc | 1 +
.../servers/pages/distributed/operate/index.adoc | 10 +-
.../servers/pages/distributed/operate/logging.adoc | 108 +++++++++++++++++++++
3 files changed, 115 insertions(+), 4 deletions(-)
diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc
index ffd4c6e..78e7f7b 100644
--- a/docs/modules/servers/nav.adoc
+++ b/docs/modules/servers/nav.adoc
@@ -11,6 +11,7 @@
*** xref:distributed/configure/index.adoc[]
*** xref:distributed/operate/index.adoc[]
**** xref:distributed/operate/guide.adoc[]
+**** xref:distributed/operate/logging.adoc[]
**** xref:distributed/operate/webadmin.adoc[]
**** xref:distributed/operate/metrics.adoc[]
**** xref:distributed/operate/cli.adoc[]
diff --git a/docs/modules/servers/pages/distributed/operate/index.adoc
b/docs/modules/servers/pages/distributed/operate/index.adoc
index 4c62a69..8b20adb 100644
--- a/docs/modules/servers/pages/distributed/operate/index.adoc
+++ b/docs/modules/servers/pages/distributed/operate/index.adoc
@@ -6,15 +6,17 @@ Once you have a Distributed James server up and running you
then need to ensure
You may also need to perform some operation maintenance or recover from
incidents. This section covers
these topics.
-The xref:main:servers:distributed:operate:webadmin.adoc[WebAdmin Restfull
administration API] is the
+Read more about link:logging.adoc[Logging].
+
+The link:webadmin.adoc[WebAdmin Restfull administration API] is the
recommended way to operate the Distributed James server. It allows managing
and interacting with most
server components.
-The xref:main:servers:distributed:operate:cli.adoc[Command line interface]
allows to interact with some
+The link:cli.adoc[Command line interface] allows to interact with some
server components. However it relies on JMX technologies and its use is
discouraged.
-The xref:main:servers:distributed:operate:metrics.adoc[metrics] allows to
build latency and throughput
+The link:metrics.adoc[metrics] allows to build latency and throughput
graphs, that can be visualized, for instance in *Grafana*.
-Finally, we did put together a
xref:main:servers:distributed:operate:metrics.adoc[detailed guide] for
+Finally, we did put together a link:metrics.adoc[detailed guide] for
distributed James operators.
diff --git a/docs/modules/servers/pages/distributed/operate/logging.adoc
b/docs/modules/servers/pages/distributed/operate/logging.adoc
new file mode 100644
index 0000000..e092b8f
--- /dev/null
+++ b/docs/modules/servers/pages/distributed/operate/logging.adoc
@@ -0,0 +1,108 @@
+= Logging
+
+We recommend to closely monitoring *ERROR* and *WARNING* logs. Those
+logs should be considered not normal.
+
+If you encounter some suspicious logs:
+
+* If you have any doubt about the log being caused by a bug in James
+source code, please reach us via the bug tracker, the user mailing list or our
Gitter channel (see our
+http://james.apache.org/#second[community page])
+* They can be due to insufficient performance from tier applications (eg
+Cassandra timeouts). In such case we advise you to conduct a close
+review of performances at the tier level.
+
+Leveraging filters in Kibana discover view can help filtering out
+``already known'' frequently occurring logs.
+
+When reporting ERROR or WARNING logs, consider adding the full logs, and
+related data (eg the raw content of a mail triggering an issue) to the
+bug report in order to ease resolution.
+
+== Logging configuration
+
+Distributed James uses link:http://logback.qos.ch/[logback] as a logging
library.
+
+Information about logback configuration can be found
+link:http://logback.qos.ch/manual/configuration.html[here].
+
+== Structured logging
+
+Distributed Server leverage the use of MDC in order to achieve structured
logging,
+and better add context to the logged information. We furthermore ship
+link:https://github.com/linagora/logback-elasticsearch-appender[Logback
Elasticsearch Appender]
+on the classpath to easily allow direct log indexation in
+link:https://www.elastic.co/elasticsearch[ElasticSearch].
+
+Here is a sample `conf/logback.xml` configuration file for logback with the
following
+pre-requisites:
+
+* Logging both in an unstructured fashion on the console and in a structure
fashion in
+ElasticSearch
+* Logging ElasticSearch Log appender logs in the console
+
+....
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration scan="true" scanPeriod="30 seconds">
+
+ <contextListener
class="ch.qos.logback.classic.jul.LevelChangePropagator">
+ <resetJUL>true</resetJUL>
+ </contextListener>
+
+ <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+ <encoder>
+ <pattern>%d{yyyy.MM.dd HH:mm:ss.SSS}
%highlight([%-5level]) %logger{15} - %msg%n%rEx</pattern>
+ <immediateFlush>false</immediateFlush>
+ </encoder>
+ </appender>
+
+ <appender name="ELASTIC"
class="com.linagora.logback.elasticsearch.ElasticsearchAppender">
+ <url>http://elasticsearch:9200/_bulk</url>
+ <index>logs-james-%date{yyyy.MM.dd}</index>
+ <type>tester</type>
+ <includeMdc>true</includeMdc>
+ <excludedMdcKeys>host</excludedMdcKeys>
+ <errorLoggerName>es-error-logger</errorLoggerName>
+ <properties>
+ <property>
+ <name>host</name>
+ <value>${HOSTNAME}</value>
+ <allowEmpty>false</allowEmpty>
+ </property>
+ <property>
+ <name>severity</name>
+ <value>%level</value>
+ </property>
+ <property>
+ <name>thread</name>
+ <value>%thread</value>
+ </property>
+ <property>
+ <name>stacktrace</name>
+ <value>%ex</value>
+ </property>
+ <property>
+ <name>logger</name>
+ <value>%logger</value>
+ </property>
+ </properties>
+ <headers>
+ <header>
+ <name>Content-Type</name>
+ <value>application/json</value>
+ </header>
+ </headers>
+ </appender>
+
+ <root level="WARN">
+ <appender-ref ref="ELASTIC" />
+ </root>
+
+ <logger name="es-error-logger" level="DEBUG" additivity="false">
+ <appender-ref ref="CONSOLE" />
+ </logger>
+
+ <logger name="org.apache.james" level="INFO" />
+
+</configuration>
+....
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org
For additional commands, e-mail: server-dev-h...@james.apache.org
