Table of Contents
List of Tables
List of Examples
This module is an implementation of a cache system designed to work with Cassandra servers. It uses the Key-Value interface exported from the core.
The underlying client library is compatible with Cassandra versions 2.1+.
memory costs are no longer on the server
many servers can be used inside a cluster, so the memory is virtually unlimited
the cache is 100% persistent. A restart of OpenSIPS server will not affect the DB. The Cassandra DB is also persistent so it can also be restarted without loss of information.
Cassandra is an open-source project so it can be used to exchange data with various other applications
By creating a Cassandra Cluster, multiple OpenSIPS instances can easily share key-value information
The following libraries or applications must be installed before running OpenSIPS with this module loaded:
libuv
cassandra-cpp-driver
The DataStax C/C++ driver for Cassandra and the libuv dependency can be downloaded from: http://downloads.datastax.com/cpp-driver/.
The urls of the server groups that OpenSIPS will connect to in order to use the from script cache_store,cache_fetch, etc operations. It can be set more than one time. The prefix part of the URL will be the identifier that will be used from the script.
Cassandra does not support regular columns in a table that contains any counter columns so in order to use the add()/sub()/get_counter() methods in the Key-Value Interface you can specify an extra table reserved only for counters.
The database part of the URL needs to be in the format Keyspace.Table[.CountersTable].
Example 1.1. Set cachedb_url parameter
...
modparam("cachedb_cassandra", "cachedb_url",
"cassandra:group1://localhost:9042/keyspace1.users.counters");
# Defining multiple contact points for a Cassandra cluster
modparam("cachedb_cassandra", "cachedb_url",
"cassandra:cluster1://10.0.0.10,10.0.0.15/keyspace2.keys.counters");
...
Example 1.2. Use Cassandra servers
...
cache_store("cassandra:group1","key","$ru value");
cache_fetch("cassandra:cluster1","key",$avp(10));
cache_remove("cassandra:cluster1","key");
...
The timeout in ms that will be triggered in case a connection attempt fails.
Default value is “5000”.
Example 1.3. Set connect_timeout parameter
...
modparam("cachedb_cassandra", "connect_timeout",1000);
...
The timeout in ms that will be triggered in case a Cassandra query takes too long.
Default value is “5000”.
Example 1.4. Set query_timeout parameter
...
modparam("cachedb_cassandra", "query_timeout",1000);
...
The consistency level desired for write operations. Options are :
all - A write must be written to the commit log and memtable on all replica nodes in the cluster for that partition.
each_quorum - Strong consistency. A write must be written to the commit log and memtable on a quorum of replica nodes in each datacenter.
quorum - A write must be written to the commit log and memtable on a quorum of replica nodes across all datacenters.
local_quorum - Strong consistency. A write must be written to the commit log and memtable on a quorum of replica nodes in the same datacenter as the coordinator. Avoids latency of inter-datacenter communication.
one - A write must be written to the commit log and memtable of at least one replica node.
two - A write must be written to the commit log and memtable of at least two replica node.
three - A write must be written to the commit log and memtable of at least three replica node.
local_one - A write must be sent to, and successfully acknowledged by, at least one replica node in the local datacenter.
any - A write must be written to at least one node. If all replica nodes for the given partition key are down, the write can still succeed after a hinted handoff has been written. If all replica nodes are down at write time, an ANY write is not readable until the replica nodes for that partition have recovered.
Default value is one.
Example 1.5. Set wr_consistency_level parameter
...
modparam("cachedb_cassandra", "wr_consistency_level", "each_quorum");
...
The consistency level desired for write operations. Options are :
all - Returns the record after all replicas have responded. The read operation will fail if a replica does not respond.
quorum - Returns the record after a quorum of replicas from all datacenters has responded.
local_quorum - Returns the record after a quorum of replicas in the current datacenter as the coordinator has reported. Avoids latency of inter-datacenter communication.
one - Returns a response from the closest replica, as determined by the snitch. By default, a read repair runs in the background to make the other replicas consistent.
two - Returns the most recent data from two of the closest replicas.
three - Returns the most recent data from three of the closest replicas.
local_one - Returns a response from the closest replica in the local datacenter.
serial - Allows reading the current (and possibly uncommitted) state of data without proposing a new addition or update. If a SERIAL read finds an uncommitted transaction in progress, it will commit the transaction as part of the read. Similar to QUORUM.
local_serial - Same as SERIAL, but confined to the datacenter. Similar to LOCAL_QUORUM.
Default value is one.
Example 1.6. Set rd_consistency_level parameter
...
modparam("cachedb_cassandra", "rd_consistency_level", "quorum");
...
A cassandra cache query that lasts more than this threshold will trigger a warning message to the log.
This value, if set, only makes sense to be lower than the query_timeout since any query taking longer than that value will be dropped anyway.
Default value is “0 ( unlimited - no warnings )”.
Example 1.7. Set exec_threshold parameter
...
modparam("cachedb_cassandra", "exec_threshold", 100000)
...
The table required for supporting the cache_store()/cache_fetch()/cache_remove() functions of the Key-Value interface needs to have at least the following columns:
opensipskey - as the primary key with type "text"
opensipsval - with type "text"
The table required for supporting the cache_add()/cache_sub()/cache_counter_fetch() functions of the Key-Value interface needs to have at least the following columns:
opensipskey - as the primary key with type "text"
opensipsval - with type "counter"
Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| Name | DevScore | Commits | Lines ++ | Lines -- | |
|---|---|---|---|---|---|
| 1. | Vlad Patrascu (@rvlad-patrascu) | 373 | 13 | 1998 | 21057 |
| 2. | Vlad Paiu (@vladpaiu) | 188 | 7 | 21444 | 38 |
| 3. | Liviu Chircu (@liviuchircu) | 11 | 9 | 39 | 50 |
| 4. | Razvan Crainea (@razvancrainea) | 8 | 6 | 16 | 14 |
| 5. | fabriziopicconi | 4 | 2 | 5 | 5 |
| 6. | Maksym Sobolyev (@sobomax) | 4 | 2 | 3 | 3 |
| 7. | Bogdan-Andrei Iancu (@bogdan-iancu) | 4 | 2 | 3 | 1 |
| 8. | Julián Moreno Patiño | 3 | 1 | 1 | 1 |
| 9. | Peter Lemenkov (@lemenkov) | 3 | 1 | 1 | 1 |
| 10. | Jarrod Baumann (@jarrodb) | 2 | 1 | 2 | 0 |
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 2.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Maksym Sobolyev (@sobomax) | Feb 2023 - Feb 2023 |
| 2. | Liviu Chircu (@liviuchircu) | Mar 2014 - Apr 2021 |
| 3. | Razvan Crainea (@razvancrainea) | Feb 2012 - Jan 2021 |
| 4. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - Jun 2020 |
| 5. | Bogdan-Andrei Iancu (@bogdan-iancu) | Oct 2014 - Apr 2019 |
| 6. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
| 7. | Julián Moreno Patiño | Feb 2016 - Feb 2016 |
| 8. | Jarrod Baumann (@jarrodb) | May 2015 - May 2015 |
| 9. | fabriziopicconi | Apr 2014 - Apr 2014 |
| 10. | Vlad Paiu (@vladpaiu) | Dec 2011 - Nov 2013 |
(1) including any documentation-related commits, excluding merge commits
Last edited by: Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu), Julián Moreno Patiño, Vlad Paiu (@vladpaiu), Razvan Crainea (@razvancrainea).
Documentation Copyrights:
Copyright © 2011 www.opensips-solutions.com