📖 Document CETS as an alternative to Mnesia #4130

arcusfelis · 2023-09-25T17:20:23Z

This PR addresses MIM-1995.

Proposed changes include:

Add information to User’s Guide / Tutorials how to set up MIM with RDBMS + CETS.
Update all docs relying on Mnesia configuration and commands like running_db_nodes to also show the CETS alternatives.
Uses tabs in documentation (like window tabs, not indention tabs).

Add information to User’s Guide / Tutorials how to set up MIM with RDBMS + CETS. Update all docs relying on Mnesia configuration and commands like running_db_nodes to also show the CETS alternatives. Uses tabs in documentation.

mongoose-im · 2023-09-25T17:28:02Z

elasticsearch_and_cassandra_25 / elasticsearch_and_cassandra_mnesia / 46c6b6e
Reports root/ big
OK: 369 / Failed: 0 / User-skipped: 38 / Auto-skipped: 0

small_tests_24 / small_tests / 46c6b6e
Reports root / small

small_tests_25 / small_tests / 46c6b6e
Reports root / small

small_tests_25_arm64 / small_tests / 46c6b6e
Reports root / small

ldap_mnesia_24 / ldap_mnesia / 46c6b6e
Reports root/ big
OK: 2276 / Failed: 0 / User-skipped: 860 / Auto-skipped: 0

ldap_mnesia_25 / ldap_mnesia / 46c6b6e
Reports root/ big
OK: 2276 / Failed: 0 / User-skipped: 860 / Auto-skipped: 0

dynamic_domains_pgsql_mnesia_24 / pgsql_mnesia / 46c6b6e
Reports root/ big
OK: 4236 / Failed: 0 / User-skipped: 112 / Auto-skipped: 0

dynamic_domains_mysql_redis_25 / mysql_redis / 46c6b6e
Reports root/ big
OK: 4204 / Failed: 0 / User-skipped: 144 / Auto-skipped: 0

dynamic_domains_pgsql_mnesia_25 / pgsql_mnesia / 46c6b6e
Reports root/ big
OK: 4236 / Failed: 0 / User-skipped: 112 / Auto-skipped: 0

dynamic_domains_mssql_mnesia_25 / odbc_mssql_mnesia / 46c6b6e
Reports root/ big
OK: 4233 / Failed: 0 / User-skipped: 115 / Auto-skipped: 0

internal_mnesia_25 / internal_mnesia / 46c6b6e
Reports root/ big
OK: 2422 / Failed: 0 / User-skipped: 714 / Auto-skipped: 0

mysql_redis_25 / mysql_redis / 46c6b6e
Reports root/ big
OK: 4605 / Failed: 0 / User-skipped: 139 / Auto-skipped: 0

pgsql_mnesia_24 / pgsql_mnesia / 46c6b6e
Reports root/ big
OK: 4625 / Failed: 0 / User-skipped: 119 / Auto-skipped: 0

pgsql_cets_25 / pgsql_cets / 46c6b6e
Reports root/ big
OK: 4623 / Failed: 0 / User-skipped: 121 / Auto-skipped: 0

pgsql_mnesia_25 / pgsql_mnesia / 46c6b6e
Reports root/ big
OK: 4625 / Failed: 0 / User-skipped: 119 / Auto-skipped: 0

mssql_mnesia_25 / odbc_mssql_mnesia / 46c6b6e
Reports root/ big
OK: 4622 / Failed: 0 / User-skipped: 122 / Auto-skipped: 0

codecov · 2023-09-25T17:28:51Z

Codecov Report

All modified lines are covered by tests ✅

Comparison is base (dd13079) 83.94% compared to head (4b8a0ca) 83.95%.
Report is 38 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4130   +/-   ##
=======================================
  Coverage   83.94%   83.95%           
=======================================
  Files         553      553           
  Lines       33661    33661           
=======================================
+ Hits        28257    28259    +2     
+ Misses       5404     5402    -2

see 10 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

NelsonVides · 2023-09-25T20:46:49Z

doc/tutorials/CETS-configure.md

+[CETS](https://github.com/esl/cets/) is a library, which allows to replicate in-memory data
+across the MongooseIM cluster. It could be used to store a list of online XMPP sessions, a list
+of outgoung S2S connections, steam management session IDs, a list of online MUC rooms.


I'd prefer to say "a set" instead of "a list", as the term list already has a very specific meaning in Erlang that is not what we're really storing here. But maybe this is not important, dunno, what do other devs think? 🤔

NelsonVides · 2023-09-25T20:47:23Z

doc/tutorials/CETS-configure.md

+
+If you want to use CETS instead of Mnesia, ensure that these options are set:
+
+```ini


Wait, markdown recognises toml here, it can be

Suggested change

```ini

```toml

doc/tutorials/CETS-configure.md

NelsonVides · 2023-09-25T20:59:53Z

doc/configuration/database-backends-configuration.md

+* CETS - a library to synchronise records from the ETS tables between nodes.
+  A new choice to share the live data across the MongooseIM cluster.
+  We recommend to use this backend for transient data.
+  This backend requires an RDBMS database configured because we use an external database to discover nodes in the cluster.
+  Check for CETS config example in [tutorials](../tutorials/CETS-configure.md).


Suggested change

* CETS - a library to synchronise records from the ETS tables between nodes.

A new choice to share the live data across the MongooseIM cluster.

We recommend to use this backend for transient data.

This backend requires an RDBMS database configured because we use an external database to discover nodes in the cluster.

Check for CETS config example in [tutorials](../tutorials/CETS-configure.md).

* CETS - a library to synchronise ETS tables between nodes.

A new choice to share live data across the MongooseIM cluster.

We recommend to use this backend for transient data.

This backend requires an RDBMS database configured because we use an external database to discover nodes in the cluster.

For a CETS config example, see [tutorials](../tutorials/CETS-configure.md).

NelsonVides · 2023-09-25T21:01:10Z

doc/configuration/database-backends-configuration.md

+* Mnesia - a built-in Erlang Database.
+  Mnesia is fine for the cluster of the fixed size with reliable networking between nodes and with nodes rarely restarted.
+  There are some issues when nodes are restarting or joining the cluster. So, we recommend to use CETS instead.
+  Mnesia is still a default backend for modules for config compatibility reasons.


Suggested change

* Mnesia - a built-in Erlang Database.

Mnesia is fine for the cluster of the fixed size with reliable networking between nodes and with nodes rarely restarted.

There are some issues when nodes are restarting or joining the cluster. So, we recommend to use CETS instead.

Mnesia is still a default backend for modules for config compatibility reasons.

* Mnesia - a built-in Erlang Database.

Mnesia is fine for a cluster of fixed size with reliable networking between nodes and with nodes rarely restarted.

There are some issues when nodes are restarting or new ones joining the cluster. For this case, we recommend to use CETS instead.

Mnesia is still the default backend for some modules for compatibility reasons with older config files.

NelsonVides · 2023-09-25T21:06:45Z

doc/operation-and-maintenance/Cluster-configuration-and-node-management.md

-mongooseimctl leave_cluster
-```
+    Stopping the node is enough to leave the cluster.
+    If you want to avoid the node to join the cluster again, you have to specify a different `cluster_name`


Suggested change

If you want to avoid the node to join the cluster again, you have to specify a different `cluster_name`

If you want to avoid the node joining the cluster again, you have to specify a different `cluster_name`

NelsonVides · 2023-09-25T21:07:13Z

doc/operation-and-maintenance/Cluster-configuration-and-node-management.md

-```text
-The node mongooseim2@localhost has successfully left the cluster
-```
+    It only makes sense to use it if the node is the part of a cluster, e.g `join_cluster` was called from that node before.


Suggested change

It only makes sense to use it if the node is the part of a cluster, e.g `join_cluster` was called from that node before.

It only makes sense to use it if the node is part of a cluster, e.g `join_cluster` was called on that node before.

NelsonVides · 2023-09-25T21:08:07Z

doc/operation-and-maintenance/Cluster-configuration-and-node-management.md

-```bash
-mongooseimctl mnesia info | grep "stopped db nodes"
-```
+    where `RemoteNodeName` is a name of the node that we'd like to remove from our cluster.


Suggested change

where `RemoteNodeName` is a name of the node that we'd like to remove from our cluster.

where `RemoteNodeName` is the name of the node that we'd like to remove from our cluster.

NelsonVides · 2023-09-25T21:10:54Z

doc/operation-and-maintenance/Cluster-configuration-and-node-management.md

+    You can check `unavailableNodes`, `remoteNodesWithUnknownTables`,
+    `remoteNodesWithMissingTables` lists for more information (generally, these lists should be empty).


Suggested change

You can check `unavailableNodes`, `remoteNodesWithUnknownTables`,

`remoteNodesWithMissingTables` lists for more information (generally, these lists should be empty).

You can check the `unavailableNodes`, `remoteNodesWithUnknownTables`,

and `remoteNodesWithMissingTables` lists for more information (generally, these lists should be empty).

NelsonVides · 2023-09-25T21:11:30Z

doc/operation-and-maintenance/Cluster-configuration-and-node-management.md

+    ```bash
+    running db nodes = [mongooseim@node1, mongooseim@node2]
+    ```
+    To see stopped or misbehaving nodes following command can be useful:


Suggested change

To see stopped or misbehaving nodes following command can be useful:

To see stopped or misbehaving nodes the following command can be useful:

mongoose-im · 2023-09-26T15:08:01Z

elasticsearch_and_cassandra_25 / elasticsearch_and_cassandra_mnesia / df1d1a9
Reports root/ big
OK: 369 / Failed: 0 / User-skipped: 38 / Auto-skipped: 0

small_tests_24 / small_tests / df1d1a9
Reports root / small

small_tests_25_arm64 / small_tests / df1d1a9
Reports root / small

small_tests_25 / small_tests / df1d1a9
Reports root / small

ldap_mnesia_24 / ldap_mnesia / df1d1a9
Reports root/ big
OK: 2276 / Failed: 0 / User-skipped: 860 / Auto-skipped: 0

ldap_mnesia_25 / ldap_mnesia / df1d1a9
Reports root/ big
OK: 2276 / Failed: 0 / User-skipped: 860 / Auto-skipped: 0

dynamic_domains_mysql_redis_25 / mysql_redis / df1d1a9
Reports root/ big
OK: 4204 / Failed: 0 / User-skipped: 144 / Auto-skipped: 0

dynamic_domains_pgsql_mnesia_25 / pgsql_mnesia / df1d1a9
Reports root/ big
OK: 4236 / Failed: 0 / User-skipped: 112 / Auto-skipped: 0

dynamic_domains_pgsql_mnesia_24 / pgsql_mnesia / df1d1a9
Reports root/ big
OK: 4235 / Failed: 1 / User-skipped: 112 / Auto-skipped: 0

service_mongoose_system_metrics_SUITE:module_opts:module_opts_are_reported

{error,
  {{assertEqual,
     [{module,service_mongoose_system_metrics_SUITE},
      {line,370},
      {expression,
        "is_module_opt_reported ( atom_to_binary ( Module ) , Key , Value )"},
      {expected,true},
      {value,false}]},
   [{service_mongoose_system_metrics_SUITE,check_module_opt,3,
      [{file,
         "/home/circleci/project/big_tests/tests/service_mongoose_system_metrics_SUITE.erl"},
       {line,370}]},
    {service_mongoose_system_metrics_SUITE,module_opts_are_reported,1,
      [{file,
         "/home/circleci/project/big_tests/tests/service_mongoose_system_metrics_SUITE.erl"},
       {line,222}]},
    {test_server,ts_tc,3,[{file,"test_server.erl"},{line,1783}]},
    {test_server,run_test_case_eval1,6,
      [{file,"test_server.erl"},{line,1292}]},
    {test_server,run_test_case_eval,9,
      [{file,"test_server.erl"},{line,1224}]}]}}

Report log

pgsql_cets_25 / pgsql_cets / df1d1a9
Reports root/ big
OK: 4623 / Failed: 0 / User-skipped: 121 / Auto-skipped: 0

internal_mnesia_25 / internal_mnesia / df1d1a9
Reports root/ big
OK: 2422 / Failed: 0 / User-skipped: 714 / Auto-skipped: 0

dynamic_domains_mssql_mnesia_25 / odbc_mssql_mnesia / df1d1a9
Reports root/ big
OK: 4233 / Failed: 0 / User-skipped: 115 / Auto-skipped: 0

mysql_redis_25 / mysql_redis / df1d1a9
Reports root/ big
OK: 4605 / Failed: 0 / User-skipped: 139 / Auto-skipped: 0

pgsql_mnesia_25 / pgsql_mnesia / df1d1a9
Reports root/ big
OK: 4625 / Failed: 0 / User-skipped: 119 / Auto-skipped: 0

pgsql_mnesia_24 / pgsql_mnesia / df1d1a9
Reports root/ big
OK: 4625 / Failed: 0 / User-skipped: 119 / Auto-skipped: 0

mssql_mnesia_25 / odbc_mssql_mnesia / df1d1a9
Reports root/ big
OK: 4622 / Failed: 0 / User-skipped: 122 / Auto-skipped: 0

NelsonVides

LGTM. But it'd be good someone else also reviews, if only to check if any information is missing. The one already here seems very good to me :)

chrzaszcz

Looks good - only minor comments from me.

doc/operation-and-maintenance/MongooseIM-metrics.md

doc/operation-and-maintenance/Cluster-configuration-and-node-management.md

doc/tutorials/CETS-configure.md

mongoose-im · 2023-09-27T09:00:53Z

elasticsearch_and_cassandra_25 / elasticsearch_and_cassandra_mnesia / 4b8a0ca
Reports root/ big
OK: 369 / Failed: 0 / User-skipped: 38 / Auto-skipped: 0

small_tests_24 / small_tests / 4b8a0ca
Reports root / small

small_tests_25_arm64 / small_tests / 4b8a0ca
Reports root / small

small_tests_25 / small_tests / 4b8a0ca
Reports root / small

ldap_mnesia_24 / ldap_mnesia / 4b8a0ca
Reports root/ big
OK: 2276 / Failed: 0 / User-skipped: 860 / Auto-skipped: 0

dynamic_domains_mysql_redis_25 / mysql_redis / 4b8a0ca
Reports root/ big
OK: 4204 / Failed: 0 / User-skipped: 144 / Auto-skipped: 0

dynamic_domains_pgsql_mnesia_25 / pgsql_mnesia / 4b8a0ca
Reports root/ big
OK: 4236 / Failed: 0 / User-skipped: 112 / Auto-skipped: 0

dynamic_domains_pgsql_mnesia_24 / pgsql_mnesia / 4b8a0ca
Reports root/ big
OK: 4236 / Failed: 0 / User-skipped: 112 / Auto-skipped: 0

ldap_mnesia_25 / ldap_mnesia / 4b8a0ca
Reports root/ big
OK: 2276 / Failed: 0 / User-skipped: 860 / Auto-skipped: 0

dynamic_domains_mssql_mnesia_25 / odbc_mssql_mnesia / 4b8a0ca
Reports root/ big
OK: 4233 / Failed: 0 / User-skipped: 115 / Auto-skipped: 0

internal_mnesia_25 / internal_mnesia / 4b8a0ca
Reports root/ big
OK: 2422 / Failed: 0 / User-skipped: 714 / Auto-skipped: 0

pgsql_cets_25 / pgsql_cets / 4b8a0ca
Reports root/ big
OK: 4623 / Failed: 0 / User-skipped: 121 / Auto-skipped: 0

mysql_redis_25 / mysql_redis / 4b8a0ca
Reports root/ big
OK: 4605 / Failed: 0 / User-skipped: 139 / Auto-skipped: 0

mssql_mnesia_25 / odbc_mssql_mnesia / 4b8a0ca
Reports root/ big
OK: 4622 / Failed: 0 / User-skipped: 122 / Auto-skipped: 0

pgsql_mnesia_25 / pgsql_mnesia / 4b8a0ca
Reports root/ big
OK: 4625 / Failed: 0 / User-skipped: 119 / Auto-skipped: 0

pgsql_mnesia_24 / pgsql_mnesia / 4b8a0ca
Reports root/ big
OK: 4625 / Failed: 0 / User-skipped: 119 / Auto-skipped: 0

📖 Document CETS as an alternative to Mnesia

46c6b6e

Add information to User’s Guide / Tutorials how to set up MIM with RDBMS + CETS. Update all docs relying on Mnesia configuration and commands like running_db_nodes to also show the CETS alternatives. Uses tabs in documentation.

arcusfelis marked this pull request as ready for review September 25, 2023 18:14

NelsonVides reviewed Sep 25, 2023

View reviewed changes

Apply review changes requested by @NelsonVides

df1d1a9

NelsonVides approved these changes Sep 26, 2023

View reviewed changes

chrzaszcz reviewed Sep 27, 2023

View reviewed changes

doc/operation-and-maintenance/MongooseIM-metrics.md Outdated Show resolved Hide resolved

doc/operation-and-maintenance/Cluster-configuration-and-node-management.md Outdated Show resolved Hide resolved

doc/tutorials/CETS-configure.md Outdated Show resolved Hide resolved

Apply review changes requested by @chrzaszcz

4b8a0ca

chrzaszcz merged commit c5d0b24 into master Sep 27, 2023

chrzaszcz deleted the update-cets-docs branch September 27, 2023 09:35

chrzaszcz added this to the 6.2.0 milestone Dec 11, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📖 Document CETS as an alternative to Mnesia #4130

📖 Document CETS as an alternative to Mnesia #4130

arcusfelis commented Sep 25, 2023

mongoose-im commented Sep 25, 2023 •

edited

Loading

codecov bot commented Sep 25, 2023 •

edited

Loading

NelsonVides Sep 25, 2023

NelsonVides Sep 25, 2023

NelsonVides Sep 25, 2023

NelsonVides Sep 25, 2023

NelsonVides Sep 25, 2023

NelsonVides Sep 25, 2023

NelsonVides Sep 25, 2023

NelsonVides Sep 25, 2023

NelsonVides Sep 25, 2023

mongoose-im commented Sep 26, 2023 •

edited

Loading

NelsonVides left a comment

chrzaszcz left a comment

mongoose-im commented Sep 27, 2023 •

edited

Loading


		If you want to use CETS instead of Mnesia, ensure that these options are set:

		```ini

	If you want to avoid the node to join the cluster again, you have to specify a different `cluster_name`
	If you want to avoid the node joining the cluster again, you have to specify a different `cluster_name`

	It only makes sense to use it if the node is the part of a cluster, e.g `join_cluster` was called from that node before.
	It only makes sense to use it if the node is part of a cluster, e.g `join_cluster` was called on that node before.

	where `RemoteNodeName` is a name of the node that we'd like to remove from our cluster.
	where `RemoteNodeName` is the name of the node that we'd like to remove from our cluster.

		You can check `unavailableNodes`, `remoteNodesWithUnknownTables`,
		`remoteNodesWithMissingTables` lists for more information (generally, these lists should be empty).

	To see stopped or misbehaving nodes following command can be useful:
	To see stopped or misbehaving nodes the following command can be useful:

📖 Document CETS as an alternative to Mnesia #4130

📖 Document CETS as an alternative to Mnesia #4130

Conversation

arcusfelis commented Sep 25, 2023

mongoose-im commented Sep 25, 2023 • edited Loading

codecov bot commented Sep 25, 2023 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mongoose-im commented Sep 26, 2023 • edited Loading

NelsonVides left a comment

Choose a reason for hiding this comment

chrzaszcz left a comment

Choose a reason for hiding this comment

mongoose-im commented Sep 27, 2023 • edited Loading

mongoose-im commented Sep 25, 2023 •

edited

Loading

codecov bot commented Sep 25, 2023 •

edited

Loading

mongoose-im commented Sep 26, 2023 •

edited

Loading

mongoose-im commented Sep 27, 2023 •

edited

Loading