[james-project] 03/09: JAMES-3047 DistributedJames guide skeleton

[bt...@apache.org]

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 c04c9d47fd1288663d199e2390b2b8527b7288fb
Author: Benoit Tellier <bt...@linagora.com>
AuthorDate: Tue Feb 11 15:29:42 2020 +0700

    JAMES-3047 DistributedJames guide skeleton
    
    Includes:
     - High level storage architecture overview
     - Basic monitoring including logs, metrics and healthChecks
    
    It will be enriched with procedures for diagnosed problems.
---
 .../server/manage-guice-distributed-james.md       | 93 ++++++++++++++++++++++
 1 file changed, 93 insertions(+)

diff --git a/src/site/markdown/server/manage-guice-distributed-james.md b/src/site/markdown/server/manage-guice-distributed-james.md
new file mode 100644
index 0000000..8a2532a
--- /dev/null
+++ b/src/site/markdown/server/manage-guice-distributed-james.md
@@ -0,0 +1,93 @@
+# Managing Guice distributed James
+
+This guide aims to be an entry-point to the James documentation for user managing a distributed Guice James server.
+
+It includes:
+
+ - Simple architecture explanations
+ - Propose some diagnostics for some common issues
+ - Present procedures that can be set up to address these issues
+
+In order to not duplicate information, existing documentation will be linked.
+
+Please note that this product is under active development, should be considered experimental and thus targets 
+advanced users.
+
+## Table of content
+
+ - [Overall architecture](#overall-architecture)
+ - [Basic Monitoring](#basic-monitoring)
+
+## Overall architecture
+
+Guice distributed James server intends to provide a horizontally scalable email server.
+
+In order to achieve this goal, this product leverages the following technologies:
+
+ - **Cassandra** for meta-data storage
+ - **ObjectStorage** (S3) for binary content storage
+ - **ElasticSearch** for search
+ - **RabbitMQ** for messaging
+
+A [docker-compose](https://github.com/apache/james-project/blob/master/dockerfiles/run/docker-compose.yml) file is 
+available to allow you to quickly deploy locally this product.
+
+## Basic Monitoring
+
+A toolbox is available to help an administrator diagnose issues:
+ - [Structured logging into Kibana](#structured-logging-into-kibana)
+ - [Metrics graphs into Grafana](#metrics-graphs-into-grafana)
+ - [WebAdmin HealthChecks](#webadmin-healthchecks)
+
+### Structured logging into Kibana
+
+Read this page regarding [setting up structured logging](monitor-logging.html#Guice_products_and_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 [community page](http://james.apache.org/#second))
+ - 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.
+
+### Metrics graphs into Grafana
+
+James keeps tracks of various metrics and allow to easily visualize them.
+
+Read this page for [explanations on metrics](metrics.html).
+
+Here is a list of [available metric boards](https://github.com/apache/james-project/tree/master/grafana-reporting)
+
+Configuration of [ElasticSearch metric exporting](config-elasticsearch.html) allows a direct display within 
+[Grafana](https://grafana.com/)
+
+Monitoring these graphs on a regular basis allows diagnosing early some performance issues. 
+
+If some metrics seem abnormally slow despite in depth database performance tuning, feedback is appreciated as well on 
+the bug tracker, the user mailing list or our Gitter channel (see our [community page](http://james.apache.org/#second))
+. Any additional details categorizing the slowness are appreciated as well (details of the slow requests for instance).
+
+### WebAdmin HealthChecks
+
+James webadmin API allows to run healthChecks for a quick health overview.
+
+Here is related [webadmin documentation](manage-webadmin.html#HealthCheck)
+
+Here are the available checks alongside the insight they offer:
+
+ - **Cassandra backend**: Cassandra storage. Ensure queries can be executed on the connection James uses.
+ - **ElasticSearch Backend**: ElasticSearch storage. Triggers an ElasticSearch health request on indices James uses.
+ - **RabbitMQ backend**: RabbitMQ messaging. Verifies an open connection and an open channel are well available.
+ - **Guice application lifecycle**: Ensures James Guice successfully started, and is up. Logs should contain explanations if
+ James did not start well.
+ - **MessageFastViewProjection**: Follows MessageFastViewProjection cache miss rates and warns if it is below 10%. If this 
+ projection is missing, this results in performance issues for JMAP GetMessages list requests. WebAdmin offers a
+ [global](manage-webadmin.html#recomputing-global-jmap-fast-message-view-projection) and 
+ [per user](manage-webadmin.html#recomputing-user-jmap-fast-message-view-projection) projection re-computation. Note that
+ as computation is asynchronous, this projection can be slightly out of sync on a normally behaving server.
\ No newline at end of file


---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org